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
- 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
1---2name: n8n-errors-connection3description: 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.4license: MIT5---6
7# n8n Connection Error Diagnosis & Resolution
8
9> Deterministic diagnostic guide for all n8n v1.x connection failures.
10> Format: Symptom -> Cause -> Fix. ALWAYS follow the diagnostic tables.
11
12## Quick Reference: Connection Error Categories
13
14| Category | Common Symptom | Go To |
15|----------|---------------|-------|
16| API connection | HTTP 4xx/5xx, ECONNREFUSED, ETIMEDOUT | [API Failures](#api-connection-failures) |
17| Credentials | 401 Unauthorized, 403 Forbidden | [Credential Errors](#credential-errors) |
18| Timeouts | ETIMEDOUT, ESOCKETTIMEDOUT, execution hangs | [Timeout Configuration](#timeout-configuration) |
19| SSL/TLS | UNABLE_TO_VERIFY_LEAF_SIGNATURE, CERT_HAS_EXPIRED | [SSL/TLS Errors](#ssltls-errors) |
20| Webhooks | Webhook not triggering, 404 on webhook URL | [Webhook URL Issues](#webhook-url-issues) |
21| Rate limiting | 429 Too Many Requests | [Rate Limiting](#rate-limiting) |
22| Queue mode | Redis ECONNREFUSED, worker not picking up jobs | [Queue Mode (Redis)](#queue-mode-redis-connection) |
23| Database | ECONNREFUSED on 5432, SQLite SQLITE_BUSY | [Database Errors](#database-connection-errors) |
24
25---
26
27## API Connection Failures
28
29| Symptom | Cause | Fix |
30|---------|-------|-----|
31| `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. |
32| `ENOTFOUND` (DNS) | Hostname cannot be resolved | ALWAYS check for typos in the URL. Verify DNS resolution from the n8n host with `nslookup` or `dig`. |
33| `ETIMEDOUT` | Network unreachable or firewall blocking | ALWAYS check firewall rules, security groups, and network connectivity from the n8n container/host. |
34| 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. |
35| HTTP 502/503 | Upstream service unavailable | Check if the target service is overloaded or restarting. Use retry-on-fail configuration. |
36| `ECONNRESET` | Connection dropped mid-request | Typically a network instability issue. Enable retry-on-fail on the node. |
37| Proxy errors | Corporate proxy blocking requests | Set `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables. See [references/methods.md](references/methods.md). |
38
39---
40
41## Credential Errors
42
43| Symptom | Cause | Fix |
44|---------|-------|-----|
45| 401 Unauthorized | Invalid API key, expired token, wrong credentials | ALWAYS verify credentials in n8n Settings > Credentials. Re-enter the API key or regenerate it. |
46| 403 Forbidden | Credentials valid but insufficient permissions | Check API key scopes/permissions on the target service. NEVER assume n8n grants permissions. |
47| "Credential not found" | Credential deleted or not shared with workflow owner | Re-create the credential or share it with the correct project/user. |
48| 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. |
49| 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. |
50| `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. |
51
52---
53
54## Timeout Configuration
55
56Three timeout levels exist in n8n. ALWAYS configure from specific to general.
57
58### Level 1: Node-Level (Retry on Fail)
59
60Configure in each node's **Settings** tab:
61
62| Setting | Default | Description |
63|---------|---------|-------------|
64| Retry On Fail | `false` | Enable automatic retries |
65| Max Tries | `3` | Number of retry attempts |
66| Wait Between Tries (ms) | `1000` | Delay between retries |
67
68### Level 2: Workflow-Level
69
70Set in **Workflow Settings** for per-workflow timeout.
71
72### Level 3: Instance-Level
73
74| Variable | Default | Description |
75|----------|---------|-------------|
76| `EXECUTIONS_TIMEOUT` | `-1` (disabled) | Default timeout for all workflows (seconds) |
77| `EXECUTIONS_TIMEOUT_MAX` | `3600` | Maximum timeout users can set (seconds) |
78| `N8N_AI_TIMEOUT_MAX` | `3600000` | AI/LLM node HTTP timeout (ms) |
79
80ALWAYS set `EXECUTIONS_TIMEOUT` in production to prevent runaway workflows.
81NEVER leave `EXECUTIONS_TIMEOUT` at `-1` in production environments.
82
83---
84
85## SSL/TLS Errors
86
87| Symptom | Cause | Fix |
88|---------|-------|-----|
89| `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. |
90| `CERT_HAS_EXPIRED` | Target's SSL certificate expired | Contact the target service owner. NEVER disable TLS verification in production. |
91| `DEPTH_ZERO_SELF_SIGNED_CERT` | Self-signed cert without CA chain | Add the self-signed cert to `NODE_EXTRA_CA_CERTS` environment variable. |
92| `ERR_TLS_CERT_ALTNAME_INVALID` | Certificate hostname mismatch | Verify the URL matches the certificate's Common Name or SAN entries. |
93| 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`. |
94
95NEVER set `NODE_TLS_REJECT_UNAUTHORIZED=0` in production. This disables ALL certificate validation.
96
97---
98
99## Webhook URL Issues
100
101> CRITICAL: This is the #1 source of webhook confusion in n8n.
102
103### Test vs Production URL Decision Tree
104
105```
106Is the workflow ACTIVE (published)?
107├── YES → Use PRODUCTION URL: <base>/webhook/<path>
108│ Webhook triggers automatically on incoming requests
109└── NO → Use TEST URL: <base>/webhook-test/<path>
110 MUST click "Listen for Test Event" in editor first
111```
112
113| Symptom | Cause | Fix |
114|---------|-------|-----|
115| 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. |
116| 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. |
117| Webhook returns empty response | Response mode set to "Immediately" | Change to "When Last Node Finishes" or use "Respond to Webhook" node. |
118| 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/`. |
119| Wrong webhook domain in UI | `WEBHOOK_URL` misconfigured | ALWAYS set `WEBHOOK_URL` to match the public-facing URL of your reverse proxy. |
120| Webhook payload too large | Exceeds 16MB default limit | Set `N8N_PAYLOAD_SIZE_MAX` to a higher value. |
121
122### WEBHOOK_URL Environment Variable
123
124ALWAYS set `WEBHOOK_URL` when n8n is behind a reverse proxy:
125```
126WEBHOOK_URL=https://n8n.example.com/
127```
128
129NEVER omit `WEBHOOK_URL` in production — n8n will generate localhost URLs that external services cannot reach.
130
131---
132
133## Rate Limiting
134
135| Symptom | Cause | Fix |
136|---------|-------|-----|
137| HTTP 429 Too Many Requests | API rate limit exceeded | Enable **Retry On Fail** with increasing wait times. Use the **Wait** node for explicit delays. |
138| 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. |
139| OAuth rate limits | Too many token refresh requests | Cache tokens and check expiry before refreshing. |
140
141### Backoff Strategy
142
143ALWAYS configure retry with exponential-style backoff for rate-limited APIs:
144
1451. Set **Retry On Fail** = `true` on the HTTP Request node
1462. Set **Max Tries** = `3` (or higher for aggressive rate limiters)
1473. Set **Wait Between Tries** = `2000` ms (minimum for most APIs)
1484. For additional control, use **Split In Batches** with a **Wait** node between batches
149
150---
151
152## Queue Mode (Redis) Connection
153
154| Symptom | Cause | Fix |
155|---------|-------|-----|
156| `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`. |
157| 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`. |
158| Redis AUTH failed | Wrong Redis password | Verify `QUEUE_BULL_REDIS_PASSWORD` matches Redis `requirepass` configuration. |
159| Redis timeout | Network latency or Redis overloaded | Increase `QUEUE_BULL_REDIS_TIMEOUT_THRESHOLD` (default: 10000ms). Check Redis memory usage. |
160| Executions stuck in "waiting" | Worker crashed or lost connection | Restart workers. Check worker logs for connection errors. Verify `EXECUTIONS_MODE=queue` on workers. |
161
162### Queue Mode Requirements Checklist
163
164ALWAYS verify ALL of these before enabling queue mode:
165
166- [ ] `EXECUTIONS_MODE=queue` on ALL instances
167- [ ] PostgreSQL database (NEVER SQLite with queue mode)
168- [ ] Redis running and accessible from all instances
169- [ ] Same `N8N_ENCRYPTION_KEY` on ALL instances
170- [ ] Same n8n version on ALL instances
171- [ ] `WEBHOOK_URL` set on main instance
172- [ ] S3-compatible storage configured for binary data
173
174---
175
176## Database Connection Errors
177
178| Symptom | Cause | Fix |
179|---------|-------|-----|
180| PostgreSQL `ECONNREFUSED` | Database not running or wrong host/port | Verify PostgreSQL is running. Check `DB_POSTGRESDB_HOST` and `DB_POSTGRESDB_PORT`. |
181| `password authentication failed` | Wrong database password | Verify `DB_POSTGRESDB_PASSWORD`. Use `_FILE` suffix for Docker Secrets. |
182| `database "n8n" does not exist` | Database not created | Create the database: `CREATE DATABASE n8n;` |
183| `SQLITE_BUSY` | Concurrent writes to SQLite | NEVER use SQLite in production with multiple connections. Switch to PostgreSQL. |
184| `SQLITE_CORRUPT` | Database file corrupted | Restore from backup. Run `DB_SQLITE_VACUUM_ON_STARTUP=true` after restore. |
185| Connection pool exhaustion | Too many concurrent connections | Increase `DB_POSTGRESDB_POOL_SIZE` (default: 2). Monitor with `pg_stat_activity`. |
186| Connection timeout | Slow network or overloaded DB | Increase `DB_POSTGRESDB_CONNECTION_TIMEOUT` (default: 20000ms). |
187| Idle connections dropped | Firewall/NAT killing idle connections | Decrease `DB_POSTGRESDB_IDLE_CONNECTION_TIMEOUT` (default: 30000ms) or configure `DB_PING_INTERVAL_SECONDS`. |
188
189---
190
191## Diagnostic Flowchart
192
193```
194Connection error occurred
195│
196├── Is it an HTTP status code?
197│ ├── 401/403 → Credential Errors table
198│ ├── 404 on webhook → Webhook URL Issues table
199│ ├── 429 → Rate Limiting table
200│ └── 500/502/503 → API Connection Failures table
201│
202├── Is it a Node.js error code?
203│ ├── ECONNREFUSED → Check target service is running
204│ ├── ENOTFOUND → DNS resolution issue
205│ ├── ETIMEDOUT → Firewall or network issue
206│ ├── ECONNRESET → Network instability, enable retries
207│ └── TLS/SSL errors → SSL/TLS Errors table
208│
209├── Is it a database error?
210│ ├── PostgreSQL → Database Connection Errors table
211│ └── SQLite → Switch to PostgreSQL for production
212│
213└── Is it a queue/Redis error?
214 └── Queue Mode (Redis) Connection table
215```
216
217## Reference Files
218
219- [references/methods.md](references/methods.md) — Connection error types, retry configuration, timeout settings
220- [references/examples.md](references/examples.md) — Connection error scenarios with step-by-step fixes
221- [references/anti-patterns.md](references/anti-patterns.md) — Connection handling mistakes to avoid
majiayu000