When a self-hosted n8n workflow is not running, the debugging hour splits in two: the part where everyone stares at the canvas, and the part where the actual cause — which lives outside the canvas — goes uninvestigated. The canvas was already green. Climb the ladder, lowest-cost rung first; the first two resolve ~80% of real cases.
Stage 1 — Activation state (the 30-second suspicion)
Inactive workflows never run. The toggle flips back after a hotfix edit; imports default to inactive; activations unwind when credentials expire upstream. Read the toggle before reasoning about what it "should" be.
Stage 2 — Trigger registration
Manual runs route through the editor; scheduled runs route through the trigger system. Webhooks must point at the production URL, not the test URL that dies with your tab. Cron schedules: confirm the registration survived restarts — a stale registration leaves a workflow with no heartbeat.
Stage 3 — The executions log is the decision point
Executions present with errors → the trigger fired; your bug lives in the nodes (renamed field, rejected payload). Executions absent → upstream: reachability, scheduler, or queue infrastructure. Two radically different hunts; the log tells you which you're on.
Stage 4 — Credentials on the server
The credential works on your machine. Is it present, unexpired, readable by the executing process — which, in queue mode, is not the process you're browsing? OAuth tokens die; env vars drift between containers.
Stage 5 — The network path
Reverse-proxies stripping path prefixes, WAF rules dropping POST bodies, bot protection aimed at your legitimate sender — all produce a perfectly Active workflow that receives nothing. Probe from outside with curl.
Stage 6 — When infrastructure keeps being the answer
Worker starvation and registration drift belong to the queue-mode trap list. And to shrink the next scramble: export the suspect workflow, run the free n8n workflow audit — it flags the three upstream causes (activation traps, environment-local URLs, missing retries) deterministically, in your browser, nothing uploaded.
Leave the editor. Walk the ladder. The workflow is exactly where the evidence says it is.
Top comments (0)