How to Fix ECONNREFUSED in n8n When a Workflow Calls localhost (Docker)
Inside a container, localhost means the container. Your database is somewhere else entirely, and that's the whole bug.
On this page
- The 4 fixes, and what each one costs you
- Why this happens at all
- 1. Docker Desktop: use host.docker.internal
- 2. Compose service name — the one worth doing
- 3. Linux: the host gateway
- 4. network_mode: host, and why I'd avoid it
- Match your symptom to the fix
- The same bug, but louder: n8n's own database
- When it still won't connect
The workflow runs fine on your laptop. In Docker, the HTTP Request node dies instantly:
Error: connect ECONNREFUSED 127.0.0.1:5432
The service is definitely running. You can curl it from your terminal this second. n8n still can't see it.
Nothing is broken, and nothing is misconfigured in the way you're looking for. The address simply doesn't mean what you think it means once the code asking the question is inside a container.
#The 4 fixes, and what each one costs you
| # | Fix | Works on | Survives a move to production? |
|---|---|---|---|
| 1 | host.docker.internal |
Docker Desktop (Mac, Windows) | No |
| 2 | Compose service name | Anywhere | Yes |
| 3 | Host gateway IP | Linux | Partly |
| 4 | network_mode: host |
Linux only | Rarely the right call |
#Why this happens at all
Every container gets its own network namespace. That means its own loopback interface, its own 127.0.0.1, and its own idea of what localhost means.
When the HTTP Request node resolves 127.0.0.1:5432 it is asking the container about the container, and the container has nothing listening on 5432, so the kernel refuses the connection immediately rather than waiting for anything. That immediacy is the useful diagnostic here: a refusal is an active answer from something that received your packet and declined it, which tells you the route worked and the destination was empty.
A timeout means the opposite — nothing answered at all, which points at a firewall or an address that goes nowhere. Learning to read those 2 apart saves more debugging time than any single fix in this guide.
#1. Docker Desktop: use host.docker.internal
On Mac and Windows, Docker Desktop provides a hostname that resolves to the host machine:
postgres://user:pass@host.docker.internal:5432/mydb
Change it in the n8n credential, not in the node. Credentials are shared across every workflow that uses them, so fixing it in 1 place fixes all of them.
This is the fastest fix and the least portable. It won't work on a plain Linux server without extra configuration, which is exactly where you'll deploy. Treat it as a development convenience.
#2. Compose service name — the one worth doing
If n8n and the service both live in the same docker-compose.yml, Docker gives you DNS between them for free. The service name is the hostname:
services:
n8n:
image: n8nio/n8n
ports: ["5678:5678"]
depends_on: [db]
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: example
Then the connection string is simply:
postgres://user:pass@db:5432/mydb
Note what's missing. There's no ports: entry on db, because nothing outside the Compose network needs to reach it. That's a small security win you get for free: a database that isn't published can't be scanned from outside.
This is the fix I'd use, every time, and it's worth the 10 minutes of restructuring even when host.docker.internal would have worked. It behaves identically on your laptop and on a server, which means the configuration you tested is the configuration you deploy, and the failure mode you never see in development is the one that wakes you up.
#3. Linux: the host gateway
On Linux, host.docker.internal isn't provided by default. You can add it:
services:
n8n:
image: n8nio/n8n
extra_hosts:
- "host.docker.internal:host-gateway"
host-gateway is a special value Docker resolves to the host's address on the bridge network. It makes Linux behave like Docker Desktop, which is useful when you want 1 configuration everywhere.
One catch worth knowing: the service on the host has to be listening on an address the container can reach. A process bound to 127.0.0.1 on the host is invisible to containers no matter what hostname you use. Bind it to 0.0.0.0 — and then firewall the port, because you've just exposed it more widely than before.
#4. network_mode: host, and why I'd avoid it
Putting the container directly on the host's network makes localhost work as you originally expected:
services:
n8n:
network_mode: host
It's Linux-only, it discards the isolation that made containers worth using, and every port the container opens lands straight on the host. For a quick local test, fine. For anything that stays running, it trades a 2-minute fix for a permanent weakness.
#Match your symptom to the fix
| What you're seeing | Likely cause | Go to |
|---|---|---|
ECONNREFUSED 127.0.0.1:<port> |
Container loopback, not the host | 1 or 2 |
| Works on Mac, fails on a Linux server | host.docker.internal isn't there |
3 |
| Hangs then times out | Firewall or wrong IP, not this bug | — |
EAI_AGAIN or DNS failure |
Hostname doesn't resolve at all | 2 |
| Works from a terminal in the container | Credential still has the old host | 1 |
#The same bug, but louder: n8n's own database
Everything above assumes a workflow node failing. The identical mistake in n8n's own configuration fails differently, and it's worth recognising because the symptom looks unrelated.
If you've pointed n8n at Postgres for its own storage with DB_POSTGRESDB_HOST=localhost, the container won't start at all. There's no workflow to debug and no red node to click, just a container that exits and restarts in a loop while the logs scroll past with a connection error. The fix is the same — use the Compose service name — but people spend much longer on it because a boot loop doesn't look like a networking problem.
n8n:
image: n8nio/n8n
environment:
DB_TYPE: postgresdb
DB_POSTGRESDB_HOST: db
#When it still won't connect
Test from inside the container rather than from your terminal. That's the only perspective that counts:
docker compose exec n8n sh -c "nc -vz db 5432"
A refusal means the name resolved but nothing is listening — wrong port, or the service hasn't finished starting. A DNS failure means the name is wrong or the 2 containers aren't on the same network. A hang means a firewall is dropping packets silently.
Check depends_on too. It waits for the container to start, not for the database inside it to be ready to accept connections. A workflow that fires the instant the stack comes up can hit a real refusal from a database still starting, which looks the same as this bug but isn't.
If you're weighing self-hosting against a managed service while reading this, the n8n review covers what the maintenance actually costs, and the automation shortlist compares the alternatives.
Frequently asked questions
Why ECONNREFUSED instead of a timeout?
A refusal is an active response: something received the packet and said no. A timeout means nothing answered at all. Refusal points at the wrong address or port; a timeout usually points at a firewall.
Does host.docker.internal work in production?
Not reliably. It's a Docker Desktop convenience. On Linux you have to add it yourself with extra_hosts and host-gateway, which is why a Compose service name is the better habit.
Can I use the host's LAN IP instead?
You can, and it works until the IP changes — on a laptop that's whenever you change network. Fine for a one-off test, bad in a committed configuration file.
The hostname is right and it still refuses. Now what?
Check what the service is bound to. A process listening on 127.0.0.1 only accepts connections from its own machine. It needs 0.0.0.0 to accept from a container, and then a firewall rule so that isn't a wider exposure than you meant.
Does this apply to n8n's own database too?
Yes, and it's a common first encounter with it. If n8n is configured to store its data in Postgres and the host is set to localhost, n8n won't start at all — same cause, louder symptom.
Written by
Vemuri Abhiram
Founder & Editor
I write every post here. The tools I review are ones I pay for and run on real client work, not demo accounts, and every number you see came off my own invoice or dashboard.
You might also like
How to Fix “You exceeded your current quota” (insufficient_quota) on the OpenAI API
Two different problems return 429 on the OpenAI API. One is worth retrying and one never is. Here's how to tell them apart in 2 minutes.
Vemuri Abhiram6 min read
Claude API Error 529 “overloaded_error”: What It Means and How to Handle It
What a 529 overloaded_error actually means, why retrying is correct for it, and the spend-cap 429 that will break a naive retry loop.
Vemuri Abhiram6 min read
How to Fix “Incorrect API key provided” (401 invalid_api_key) on the OpenAI API
A 401 from the OpenAI API usually isn't a bad key. Here are the 6 causes in the order they actually occur, starting with the invisible one.
Vemuri Abhiram6 min read
More from Underread, once a week.
The guides worth reading and the tests worth trusting. One email, every Friday.
No spam. Unsubscribe in one click.