Skip to main content
What can we help you with?
< All Topics
Print

n8n Debugging

Posted
Updated
ByPeter Westerman

name: n8n-debugging

description: Troubleshoot n8n workflow failures, expression errors, webhook issues, and timeout problems. Use when diagnosing failed executions, fixing expression syntax, debugging webhook routing, or investigating performance issues.

n8n Debugging

Instructions

Diagnose and fix n8n workflow execution failures in the ITI stack. All API calls require the X-N8N-API-KEY header sourced from ITI/infrastructure/n8n-dify/.env.

Reading execution history:

Via API (includes full node input/output):


source ITI/infrastructure/n8n-dify/.env
curl -s "http://localhost:5678/api/v1/executions?status=error&limit=10" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" | python3 -m json.tool

Detailed execution with node data:


curl -s "http://localhost:5678/api/v1/executions/{id}?includeData=true" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" | python3 -m json.tool

Via n8n UI: click execution in the Executions list, then click each node to inspect Input/Output tabs.

Expression engine gotchas (from Phase 3 debugging):

Pattern Status Explanation
`={{ $json.field \ \ ‘fallback’ }}` SAFE Logical OR handles empty strings correctly
={{ $json.field ?? 'fallback' }} BROKEN Nullish coalescing does not treat "" as falsy
={{ $execution.id }} SAFE Always available; use for memory session keys
={{ $json.body.query }} SAFE Direct property access on webhook body
={{ $('NodeName').item.json.field }} RISKY Works in some contexts, fails in jsonBody strings
={{ $json.body?.query }} BROKEN Optional chaining inconsistently supported
={{ String($json.field) }} BROKEN Constructor not available in all parameter contexts
={{ $json.output.replaceAll('\n', ' ') }} RISKY Works sometimes, fails in others
={{ $json.body.sessionId ?? $execution.id }} BROKEN $json.body is lost after Switch nodes; use $execution.id directly

Rule of thumb: If an expression needs more than one operator, move the logic to a Code node.

Webhook debugging:

Production path: http://localhost:5678/webhook/{path} (active workflows only) Test path: http://localhost:5678/webhook-test/{path} (when testing in n8n UI)

Common issues:

  • 404 on webhook: workflow is not published (active). Fix: publish_workflow(workflowId)
  • Empty response: missing “Respond to Webhook” node. The webhook acknowledges 200 immediately without it.
  • responseMode: lastNode vs responseMode: responseNode — use responseNode and add an explicit Respond to Webhook node for predictable behavior

Common failure modes:

Failure Symptom Diagnosis Fix
Timeout ReadTimeout in caller Execution takes > caller timeout Increase adapter timeout; check agent maxIterations
Credential expiry 401 Unauthorized in execution API key rotated or expired Update credential via n8n UI or REST API
Memory pressure n8n container OOM-killed `docker inspect iti-n8n \ grep OOMKilled` Increase container memory limit; reduce concurrent executions
Expression error ExpressionExtensionError in execution data Complex expression in node parameter Simplify expression or move to Code node
AI Agent loop Execution runs indefinitely Agent exceeds maxIterations Set maxIterations: 5-10 in agent options
Webhook 500 Caller gets 500 response Unhandled error in workflow Check execution details; add error handling

Error Monitor workflow: The “Infrastructure: Error Monitor” workflow (ID: yL5Ks9bxfoE2BMj5) uses the Error Trigger node to catch any workflow failure. Check its executions for a formatted log line containing: timestamp, workflow name, workflow ID, execution ID, and error message.

Workflow publish vs. activate:

  • publish_workflow creates a new active version and activates the workflow
  • After editing a workflow via UI or API PUT, you MUST call publish_workflow to re-activate
  • An unpublished edit is invisible to production webhooks — the previous published version continues to serve
  • This is the #1 source of “my fix didn’t work” confusion

n8n API authentication: All REST API calls require: X-N8N-API-KEY: {key} header. The key is stored in .env as N8N_API_KEY.

Performance investigation:

  1. Check execution time in n8n UI or via GET /api/v1/executions/{id}
  2. Identify the slowest node (usually AI Agent or HTTP Request)
  3. For AI Agent slowness: reduce maxIterations, simplify system prompt, remove unnecessary tools
  4. For HTTP Request slowness: check target service health, increase timeout
  5. For pipeline workflows (consulting-pipeline): expect 10-15 minutes; this is normal for 12-agent sequential execution
Table of Contents
Privacy Policy Terms and Conditions Cookie Policy