| name | n8n-errors-connection |
| description | Use when troubleshooting API connection failures, credential errors, or timeout issues in n8n. Prevents misdiagnosis by providing deterministic symptom-cause-fix tables. Covers API failures, credential errors, timeout configuration, SSL/TLS issues, webhook URL problems (test vs production), rate limiting, queue mode connection issues (Redis), database connection failures, and retry strategies. Keywords: n8n, connection, API, timeout, SSL, credential, Redis, API not connecting, timeout, SSL error, credential invalid, Redis down, webhook URL wrong..
|
| license | MIT |
| compatibility | Designed for Claude Code. Requires n8n v1.x. |
| metadata | {"author":"OpenAEC-Foundation","version":"1.0"} |
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
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:
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
