┌────────────────────────────────────────────────┐
│         THE 5-STEP DEBUG PROCESS               │
│                                                │
│  1. REPRODUCE  → Make the bug happen reliably  │
│  2. ISOLATE    → Find which node is the cause  │
│  3. INSPECT    → Look at the actual data       │
│  4. FIX        → Apply the correction          │
│  5. VERIFY     → Confirm the fix works         │
│                                                │
│  Average debug time with system: 10-15 min     │
│  Average debug time without: 1-3 hours         │
└────────────────────────────────────────────────┘

n8n Dashboard → Executions tab:

1. Filter by: Status = "Error" or Status = "Success" (for wrong output bugs)
2. Find the specific failed execution
3. Click to open it — you'll see the workflow with green (passed) and
   red (failed) nodes highlighted
4. The red node is where n8n stopped — but the CAUSE may be earlier

To debug reliably, freeze the input data:

1. Click the trigger node in a past execution
2. Click "Pin Data" (saves this exact input)
3. Now every test run uses the SAME data
4. This eliminates "it works with different data" confusion

Pro tip: Pin the data from a FAILED execution so you're debugging
the exact scenario that broke.

30-node workflow: [1] → [2] → ... → [15] → ... → [30]

Step 1: Check the output of node 15 (middle)
- Data looks correct at node 15? → Problem is in nodes 16-30
- Data looks wrong at node 15? → Problem is in nodes 1-15

Step 2: If problem is in 16-30, check node 22 (middle of 16-30)
- Correct at 22? → Problem is in 23-30
- Wrong at 22? → Problem is in 16-22

Step 3: Continue halving until you find the exact node

Binary search: 30 nodes → found in ~5 checks
Linear search: 30 nodes → up to 30 checks

Method 1: Click the node in execution view
→ Shows the exact output data for that execution
→ Compare to what you expected

Method 2: Add temporary "Set" nodes between suspicious nodes
→ Set a debug_checkpoint field
→ Run the workflow
→ Check each checkpoint's output

Method 3: Use the "Execute Node" feature
→ Right-click a node → "Execute this node only"
→ Uses pinned data from previous nodes
→ See the output without running the entire workflow

// Debug Node: Place after any suspicious node
// Logs all data passing through

const items = $input.all();
console.log('=== DEBUG ===');
console.log('Items count:', items.length);
console.log('First item keys:', Object.keys(items[0].json));
console.log('First item:', JSON.stringify(items[0].json, null, 2));

// Check for common problems
for (const item of items) {
  if (!item.json.email) {
    console.log('WARNING: Missing email in item:', item.json.id);
  }
  if (typeof item.json.amount === 'string') {
    console.log('WARNING: Amount is string, not number:', item.json.amount);
  }
}

return items; // Pass through unchanged

n8n Expression Evaluation:

Wrong: {{$json.customer.name}}
→ Error if customer is null

Safe: {{$json.customer?.name ?? "Unknown"}}
→ Returns "Unknown" if customer is null

Debug technique:
1. Click any expression field
2. The expression editor shows the CURRENT value
3. If it shows "undefined" → the path is wrong
4. Use the data browser on the left to find the correct path

Common path mistakes:
- {{$json.body.data}} vs {{$json.data}} (depends on how webhook parses)
- {{$json[0].name}} vs {{$json.name}} (array vs object)
- {{$json.items}} vs {{$node["Previous Node"].json.items}}

Cause: Previous node returned empty array
Fix: Add IF node before the failing node
    Condition: {{$json}} is not empty
    True path: Continue
    False path: Skip / Log "No data to process"

Cause: IF/Switch node routing some items to "no match"
Debug: Check the "false" output of IF nodes
Fix: Handle the false path (log, alert, or re-route)

Cause: Merge node set to "Wait" mode timing out
Fix: Increase timeout or switch to "Append" mode

Cause: Merge node creating cross-product of inputs
Debug: Count items before and after Merge
Fix: Use "Merge by Index" or "Merge by Key" instead of "Append"

Cause: Trying to use an object as a string
Wrong: {{$json.customer}} → "[object Object]"
Fix: {{$json.customer.name}} or {{JSON.stringify($json.customer)}}

Common causes:
1. Test uses pinned data, production gets different format
   Fix: Remove pins, test with real data

2. Webhook URL is different (test vs. production)
   Fix: Update the URL in the sending service

3. Credentials expire between test and production
   Fix: Refresh credentials, check expiry

4. Rate limits hit in production (higher volume)
   Fix: Add delays, implement retry pattern

□ Fix applied to the specific node
□ Run with the SAME pinned data that caused the failure → passes
□ Run with fresh/live data → passes
□ Check edge cases:
  □ Empty input (0 items)
  □ Large input (100+ items)
  □ Missing fields (null values)
  □ Wrong types (string where number expected)
□ Error handling still works (try intentional failure)
□ Monitoring alerts still fire correctly
□ Remove any debug nodes you added
□ Unpin test data
□ Document what was wrong and how you fixed it

1. DATA INSPECTOR
   [Webhook] → [Function: Log everything] → [Google Sheets: Save snapshot]
   Use: Paste any data into the webhook to inspect its structure

2. API TESTER
   [Manual Trigger] → [HTTP Request: Any API] → [Set: Format response]
   Use: Test API calls in isolation without running full workflows

3. EXPRESSION PLAYGROUND
   [Manual Trigger] → [Set: Pin sample data] → [Set: Test expressions]
   Use: Try expressions against sample data without risking production