Linux / Server

Connection refused (ECONNREFUSED)

Nothing accepted the connection at that host/port — the service isn't listening there.

What it looks like

Error: connect ECONNREFUSED 127.0.0.1:5432

What does "Connection refused (ECONNREFUSED)" mean?

Raised by a client (your app, a database driver, curl) when the target machine actively rejected the connection — nothing is listening on that port there. The message gives the exact address and port that was tried.

What causes "Connection refused (ECONNREFUSED)"?

• The target service isn't running.
• Wrong host/port.
• Bound to 127.0.0.1 but reached from another host.

How do I confirm the cause?

1. Check the address in the message is the one you meant — 127.0.0.1 inside a container means that container, not the host machine.
2. On the target machine, check the service is running and listening on that port (ss -ltnp).
3. Check the service’s bind address: if it listens only on 127.0.0.1, other machines are refused.
4. If the service has only just started, it may not be listening yet — watch its log for the line saying it is ready, then retry.

How do I fix "Connection refused (ECONNREFUSED)"?

• Start the service and confirm it's listening (ss -ltnp).
• Check host and port.
• Bind to 0.0.0.0 if it must accept external connections.

How do I stop it happening again?

• In Docker Compose, connect to other services by their service name rather than localhost.
• Add retry-with-backoff on startup for dependencies that may take a moment to come up.

Got a different error? Paste it into the Explain This Error tool → Identifies the family and the fix — runs locally, nothing uploaded.

Related errors