n8n Debugging

When something breaks, the cause is almost always:

1. Parameter misconfiguration (wrong value, wrong type, missing field).
2. Stale assumptions (different version, different behavior than you remember).
3. Paths misconfigured or misconnected (wrong output index, wrong merge input, missing wire, IF/Switch wired to the wrong branch).
4. Upstream data stripped (an intermediate node replaced $json with its own output, so downstream $json.x resolves to null even though "it should be there"). Fix: reference the stable upstream node by name ($('Earlier Node').item.json.x).
5. Item context lost (after Aggregate, Execute Once, or Split Out flows, n8n can't pair .item references deterministically, error reads like "The expression is referencing... multiple matching items"). Fix: Merge node to re-establish context, $input.all().find(...) for explicit lookup, or redesign to keep item correspondence stable (e.g., split into stateless sub-workflows).
6. Logical errors (the wires are right and the parameters are right, but the workflow does the wrong thing, same as a logic bug in code).
7. Genuine bug (rare but real).

Diagnose systematically: cheap checks first, deeper investigation only when those fail.

Non-negotiable

Believe the user. "This isn't working" means something isn't behaving as they expect, even if they describe the symptom imprecisely. Don't dismiss with "it should work" or "are you sure you're doing X?". Investigate first: the user is truth about what should happen, execution data and source are truth about what is happening. When you can't find the cause, "I don't know yet" beats a plausible-sounding fabrication.

Strong defaults (cause to cheap check)