Chapter 10: n8n — Debugging & Operations

Last Updated: 2026-03

10.2 Using the Executions Panel

1. Open http://localhost:5678.
2. Click Executions in the left sidebar.
3. Filter by Status: Error to see only failed runs.
4. Click any failed execution to open it.
5. The canvas shows each node colored by status:

• Green = success
• Red = error
• Gray = not reached

1. Click the red node to see the error message and the input data it received.

This view is the primary debugging tool. Use it first.

---

10.3 Common Expression Errors

“Cannot read properties of undefined (reading ‘fieldName’)”

The field does not exist at the path you referenced. The data shape from the previous node is different than expected.

Diagnosis:

• Click the node before the failing one.
• Look at its output data in the execution view.
• Find the actual path to the field you need.

Fix:

• Update the expression to match the actual path.
• Add an If or Code node to handle cases where the field might be missing.

“Expression is invalid”

Syntax error in the expression.

Common mistakes:

// Wrong: missing closing brace
{{ $json.name }

// Wrong: invalid JavaScript in expression
{{ $json.items.forEach(i => i.id) }}  // Array methods don't return values

// Correct
{{ $json.items.map(i => i.id).join(", ") }}

Accessing nested data

// If the response is: {"data": {"user": {"name": "Alice"}}}
{{ $json.data.user.name }}  // Correct

// If the response is: {"data": [{"name": "Alice"}]}
{{ $json.data[0].name }}    // Correct (first array item)

---

10.4 Webhook Troubleshooting

Webhook returns 404

The workflow is not active. Workflows must be published (active) for their webhooks to respond.

# Check if the workflow is active via API
curl -s "http://localhost:5678/api/v1/workflows?active=true" \
  -H "X-N8N-API-KEY: <your-api-key>"

Re-activate through the UI: open the workflow > toggle the Active switch.

Webhook returns 500

The workflow triggered but failed during execution. Check the Executions panel for the error details.

Webhook does not trigger

1. Verify the URL is correct (copy from the Webhook node settings in n8n UI).
2. Verify the HTTP method matches (POST vs GET).
3. Check that Content-Type: application/json is set if sending a JSON body.
4. Check n8n container logs for incoming request receipt:

   docker compose logs iti-n8n --since 5m | grep -i "webhook"

Test a webhook manually

curl -X POST http://localhost:5678/webhook/your-webhook-path \
  -H "Content-Type: application/json" \
  -d '{"test": "payload", "key": "value"}'

---

10.5 Timeout Issues

The default n8n workflow execution timeout is controlled by EXECUTIONS_TIMEOUT in .env. The default is often 3600 seconds (1 hour), but individual node operations may time out sooner.

HTTP Request node timeouts

The HTTP Request node has a default 30-second timeout per request. For long-running Claude API calls (especially with large context), increase the timeout:

In the HTTP Request node settings: Options > Timeout → set to 120000 (120 seconds, in milliseconds).

AI Agent node timeouts

The LangChain AI Agent node defaults to 60 seconds per LLM call. For complex multi-tool agent calls:

Set Options > Max Execution Time to a higher value.

Detecting timeout-caused failures

In the execution view, a node that times out shows:

• Error message containing “timeout” or “ETIMEDOUT”
• The node started but has no completion time

---

10.6 Execution Data Management

n8n stores every execution’s input and output data in PostgreSQL. This grows over time.

Check execution database size

docker exec iti-postgres psql -U postgres -d n8n -c \
  "SELECT pg_size_pretty(pg_database_size('n8n'));"

Configure data pruning

In n8n UI: Settings > Executions:

• Set Prune data older than to 30 days.
• Enable Save successful executions for audit purposes (optional; increases DB size).

Manually prune old executions

Via the n8n API:

# Delete executions older than 30 days
curl -X DELETE "http://localhost:5678/api/v1/executions" \
  -H "X-N8N-API-KEY: <your-api-key>" \
  -G --data-urlencode "lastId=<last-execution-id-to-keep>"

---

10.7 Monitoring Active Workflows

List all active workflows

curl -s "http://localhost:5678/api/v1/workflows?active=true" \
  -H "X-N8N-API-KEY: <your-api-key>" | python3 -m json.tool

Check if a specific workflow is active

curl -s "http://localhost:5678/api/v1/workflows/<workflow-id>" \
  -H "X-N8N-API-KEY: <your-api-key>" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['active'])"

Error monitoring workflow

ITI maintains an Error Monitor workflow (ID: yL5Ks9bxfoE2BMj5) that subscribes to n8n’s error trigger and can send alerts. Verify it is active:

curl -s "http://localhost:5678/api/v1/workflows/yL5Ks9bxfoE2BMj5" \
  -H "X-N8N-API-KEY: <your-api-key>" | python3 -c "import sys,json; d=json.load(sys.stdin); print('Active:', d['active'])"

---

10.8 n8n Container Logs

For issues that are not visible in the Executions panel (startup errors, credential decryption failures, memory issues):

# Last 100 lines of n8n logs
docker compose logs iti-n8n --tail 100

# Follow live
docker compose logs -f iti-n8n

# Filter for errors only
docker compose logs iti-n8n --since 1h | grep -i "error\|exception\|fail"

Common log messages to look for:

Log Message	Meaning
"Error triggering webhook"	Webhook fired but workflow failed
"Workflow activation failed"	Workflow could not be started (check node configuration)
"Credential not found"	A node references a deleted or renamed credential
"Migration" messages	DB migration in progress — wait for completion

---

Previous: Chapter 9 — n8n Workflow Development | Next: Chapter 11 — Dify Knowledge Bases & RAG