Docker Compose Connection Refused on Localhost: The Real Reason

Symptom

App works in container-to-container but curl localhost:PORT from the host is refused.

Root cause

The service binds to 127.0.0.1 inside its container (not 0.0.0.0), so the published port has nothing behind it.

Fix, in order

1. Check the bind address in the app configgrep -R "127.0.0.1\|localhost" *.env *.yml
2. Bind to 0.0.0.0 inside the containercommand: --host 0.0.0.0 # example for ClickHouse
3. Verify the port mapping existsdocker compose ps # look at published ports column

Prevent it coming back

Containers are not laptops: always bind 0.0.0.0 and publish ports explicitly.

Deep-dive article

Full walkthrough: Docker Compose Connection Refused on Localhost: The Real Reason on the NinjaOps blog.

Run it on clean infra

Spinning up a fresh box to reproduce or escape this error?

Managed cloud hosting

Related

Cloud & DevOps tool comparisons · Hardware build guides

NinjaOps publishes free engineering guides. Some outbound links are affiliate links: they cost you nothing and support the site.

Last reviewed 2026-10-02 · NinjaOps SEO grid · DevOps blog