n8n Connection Error Diagnosis & Resolution

Deterministic diagnostic guide for all n8n v1.x connection failures. Format: Symptom -> Cause -> Fix. ALWAYS follow the diagnostic tables.

Quick Reference: Connection Error Categories

Category	Common Symptom	Go To
API connection	HTTP 4xx/5xx, ECONNREFUSED, ETIMEDOUT	API Failures
Credentials	401 Unauthorized, 403 Forbidden	Credential Errors
Timeouts	ETIMEDOUT, ESOCKETTIMEDOUT, execution hangs	Timeout Configuration
SSL/TLS	UNABLE_TO_VERIFY_LEAF_SIGNATURE, CERT_HAS_EXPIRED	SSL/TLS Errors
Webhooks	Webhook not triggering, 404 on webhook URL	Webhook URL Issues
Rate limiting	429 Too Many Requests	Rate Limiting
Queue mode	Redis ECONNREFUSED, worker not picking up jobs	Queue Mode (Redis)
Database	ECONNREFUSED on 5432, SQLite SQLITE_BUSY	Database Errors

API Connection Failures

Symptom	Cause	Fix
`ECONNREFUSED`	Target service is down or wrong host/port	ALWAYS verify the service is running and the URL is correct. Check `host:port` in credential or node config.
`ENOTFOUND` (DNS)	Hostname cannot be resolved	ALWAYS check for typos in the URL. Verify DNS resolution from the n8n host with `nslookup` or `dig`.
`ETIMEDOUT`	Network unreachable or firewall blocking	ALWAYS check firewall rules, security groups, and network connectivity from the n8n container/host.
HTTP 500	Remote server internal error	NEVER assume this is an n8n issue. Check the target API's status page and logs. Retry after delay.
HTTP 502/503	Upstream service unavailable	Check if the target service is overloaded or restarting. Use retry-on-fail configuration.
`ECONNRESET`	Connection dropped mid-request	Typically a network instability issue. Enable retry-on-fail on the node.
Proxy errors	Corporate proxy blocking requests	Set `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables. See references/methods.md.

Credential Errors

Symptom	Cause	Fix
401 Unauthorized	Invalid API key, expired token, wrong credentials	ALWAYS verify credentials in n8n Settings > Credentials. Re-enter the API key or regenerate it.
403 Forbidden	Credentials valid but insufficient permissions	Check API key scopes/permissions on the target service. NEVER assume n8n grants permissions.
"Credential not found"	Credential deleted or not shared with workflow owner	Re-create the credential or share it with the correct project/user.
OAuth2 token expired	Refresh token flow failed	ALWAYS click "Reconnect" in the credential settings to re-authorize. Check if the OAuth app is still active.
Wrong credential type selected	Node expects different credential type	ALWAYS match the credential type to the node. Example: "Header Auth" for API key in header, "OAuth2" for OAuth flows.
`N8N_ENCRYPTION_KEY` mismatch	Credentials encrypted with different key	ALWAYS ensure `N8N_ENCRYPTION_KEY` is identical across all instances. Credentials are NOT recoverable with wrong key.

Timeout Configuration

Three timeout levels exist in n8n. ALWAYS configure from specific to general.

Level 1: Node-Level (Retry on Fail)

Configure in each node's Settings tab:

Setting	Default	Description
Retry On Fail	`false`	Enable automatic retries
Max Tries	`3`	Number of retry attempts
Wait Between Tries (ms)	`1000`	Delay between retries

Level 2: Workflow-Level

Set in Workflow Settings for per-workflow timeout.

Level 3: Instance-Level

Variable	Default	Description
`EXECUTIONS_TIMEOUT`	`-1` (disabled)	Default timeout for all workflows (seconds)
`EXECUTIONS_TIMEOUT_MAX`	`3600`	Maximum timeout users can set (seconds)
`N8N_AI_TIMEOUT_MAX`	`3600000`	AI/LLM node HTTP timeout (ms)

ALWAYS set EXECUTIONS_TIMEOUT in production to prevent runaway workflows. NEVER leave EXECUTIONS_TIMEOUT at -1 in production environments.

SSL/TLS Errors

Symptom	Cause	Fix
`UNABLE_TO_VERIFY_LEAF_SIGNATURE`	Self-signed certificate on target	Set `NODE_TLS_REJECT_UNAUTHORIZED=0` (dev only). For production: add CA cert to Node.js trust store.
`CERT_HAS_EXPIRED`	Target's SSL certificate expired	Contact the target service owner. NEVER disable TLS verification in production.
`DEPTH_ZERO_SELF_SIGNED_CERT`	Self-signed cert without CA chain	Add the self-signed cert to `NODE_EXTRA_CA_CERTS` environment variable.
`ERR_TLS_CERT_ALTNAME_INVALID`	Certificate hostname mismatch	Verify the URL matches the certificate's Common Name or SAN entries.
PostgreSQL SSL errors	`DB_POSTGRESDB_SSL_ENABLED=false` or wrong certs	Set `DB_POSTGRESDB_SSL_ENABLED=true`, provide `DB_POSTGRESDB_SSL_CA`, `DB_POSTGRESDB_SSL_CERT`, `DB_POSTGRESDB_SSL_KEY`.

NEVER set NODE_TLS_REJECT_UNAUTHORIZED=0 in production. This disables ALL certificate validation.

Webhook URL Issues

CRITICAL: This is the #1 source of webhook confusion in n8n.

Test vs Production URL Decision Tree

Is the workflow ACTIVE (published)?
├── YES → Use PRODUCTION URL: <base>/webhook/<path>
│         Webhook triggers automatically on incoming requests
└── NO  → Use TEST URL: <base>/webhook-test/<path>
          MUST click "Listen for Test Event" in editor first

Symptom	Cause	Fix
Webhook works in editor but not when deployed	Using test URL (`/webhook-test/`) in external service	ALWAYS switch to production URL (`/webhook/`) AND activate the workflow.
404 on webhook URL	Workflow not active, or wrong URL path	ALWAYS verify: (1) workflow is active, (2) URL uses `/webhook/` not `/webhook-test/`, (3) path matches node config.
Webhook returns empty response	Response mode set to "Immediately"	Change to "When Last Node Finishes" or use "Respond to Webhook" node.
Webhook not accessible externally	`WEBHOOK_URL` not set or wrong	ALWAYS set `WEBHOOK_URL` to the full public URL including protocol. Example: `WEBHOOK_URL=https://n8n.example.com/`.
Wrong webhook domain in UI	`WEBHOOK_URL` misconfigured	ALWAYS set `WEBHOOK_URL` to match the public-facing URL of your reverse proxy.
Webhook payload too large	Exceeds 16MB default limit	Set `N8N_PAYLOAD_SIZE_MAX` to a higher value.

WEBHOOK_URL Environment Variable

ALWAYS set WEBHOOK_URL when n8n is behind a reverse proxy:

WEBHOOK_URL=https://n8n.example.com/

NEVER omit WEBHOOK_URL in production — n8n will generate localhost URLs that external services cannot reach.

Rate Limiting

Symptom	Cause	Fix
HTTP 429 Too Many Requests	API rate limit exceeded	Enable Retry On Fail with increasing wait times. Use the Wait node for explicit delays.
Batch operations hitting limits	Too many items processed simultaneously	Use the Split In Batches node. ALWAYS set batch size below the API's rate limit.
OAuth rate limits	Too many token refresh requests	Cache tokens and check expiry before refreshing.

Backoff Strategy

ALWAYS configure retry with exponential-style backoff for rate-limited APIs:

Set Retry On Fail = true on the HTTP Request node
Set Max Tries = 3 (or higher for aggressive rate limiters)
Set Wait Between Tries = 2000 ms (minimum for most APIs)
For additional control, use Split In Batches with a Wait node between batches

Queue Mode (Redis) Connection

Symptom	Cause	Fix
`ECONNREFUSED` on Redis port (6379)	Redis not running or wrong host	ALWAYS verify Redis is running: `redis-cli ping` must return `PONG`. Check `QUEUE_BULL_REDIS_HOST` and `QUEUE_BULL_REDIS_PORT`.
Workers not picking up jobs	Workers not connected to same Redis/DB	ALWAYS ensure ALL instances share identical `QUEUE_BULL_REDIS_*` variables and `N8N_ENCRYPTION_KEY`.
Redis AUTH failed	Wrong Redis password	Verify `QUEUE_BULL_REDIS_PASSWORD` matches Redis `requirepass` configuration.
Redis timeout	Network latency or Redis overloaded	Increase `QUEUE_BULL_REDIS_TIMEOUT_THRESHOLD` (default: 10000ms). Check Redis memory usage.
Executions stuck in "waiting"	Worker crashed or lost connection	Restart workers. Check worker logs for connection errors. Verify `EXECUTIONS_MODE=queue` on workers.

Queue Mode Requirements Checklist

ALWAYS verify ALL of these before enabling queue mode:

EXECUTIONS_MODE=queue on ALL instances
PostgreSQL database (NEVER SQLite with queue mode)
Redis running and accessible from all instances
Same N8N_ENCRYPTION_KEY on ALL instances
Same n8n version on ALL instances
WEBHOOK_URL set on main instance
S3-compatible storage configured for binary data

Database Connection Errors

Symptom	Cause	Fix
PostgreSQL `ECONNREFUSED`	Database not running or wrong host/port	Verify PostgreSQL is running. Check `DB_POSTGRESDB_HOST` and `DB_POSTGRESDB_PORT`.
`password authentication failed`	Wrong database password	Verify `DB_POSTGRESDB_PASSWORD`. Use `_FILE` suffix for Docker Secrets.
`database "n8n" does not exist`	Database not created	Create the database: `CREATE DATABASE n8n;`
`SQLITE_BUSY`	Concurrent writes to SQLite	NEVER use SQLite in production with multiple connections. Switch to PostgreSQL.
`SQLITE_CORRUPT`	Database file corrupted	Restore from backup. Run `DB_SQLITE_VACUUM_ON_STARTUP=true` after restore.
Connection pool exhaustion	Too many concurrent connections	Increase `DB_POSTGRESDB_POOL_SIZE` (default: 2). Monitor with `pg_stat_activity`.
Connection timeout	Slow network or overloaded DB	Increase `DB_POSTGRESDB_CONNECTION_TIMEOUT` (default: 20000ms).
Idle connections dropped	Firewall/NAT killing idle connections	Decrease `DB_POSTGRESDB_IDLE_CONNECTION_TIMEOUT` (default: 30000ms) or configure `DB_PING_INTERVAL_SECONDS`.

Diagnostic Flowchart

Connection error occurred
│
├── Is it an HTTP status code?
│   ├── 401/403 → Credential Errors table
│   ├── 404 on webhook → Webhook URL Issues table
│   ├── 429 → Rate Limiting table
│   └── 500/502/503 → API Connection Failures table
│
├── Is it a Node.js error code?
│   ├── ECONNREFUSED → Check target service is running
│   ├── ENOTFOUND → DNS resolution issue
│   ├── ETIMEDOUT → Firewall or network issue
│   ├── ECONNRESET → Network instability, enable retries
│   └── TLS/SSL errors → SSL/TLS Errors table
│
├── Is it a database error?
│   ├── PostgreSQL → Database Connection Errors table
│   └── SQLite → Switch to PostgreSQL for production
│
└── Is it a queue/Redis error?
    └── Queue Mode (Redis) Connection table

Reference Files

references/methods.md — Connection error types, retry configuration, timeout settings
references/examples.md — Connection error scenarios with step-by-step fixes
references/anti-patterns.md — Connection handling mistakes to avoid

n8n-errors-connection