Skip to content
Underread.
Guides

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.

By Vemuri Abhiram6 min read
Network cables patched into a switch
Network cables patched into a switch
On this page

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.

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.