Refused = the host answered with a reset: nothing listening on that host:port.
It fails fast and the same way every time; retrying won't help.
In Docker, localhost is the container itself. Use the service name (e.g. db).
Check the port and host: 5433 vs 5432, staging vs prod.
A server bound to 127.0.0.1 is unreachable from other machines/containers.
Check from where the app runs: nc -vz host port, then ss -ltnp on the server.
Different from 'connect timed out', where nothing answers at all.
✦ Definition~90s read
What is java.net.ConnectException?
java.net.ConnectException: Connection refused is thrown when the TCP connection attempt (a SYN) gets a reset (RST) back. The target machine is reachable, but no program is accepting connections on that port, or a firewall is configured to reject them.
★
You knocked on the right building and someone shouted 'nobody by that name lives here' straight away.
Plain-English First
You knocked on the right building and someone shouted 'nobody by that name lives here' straight away. That's different from a timeout, where nobody answers the door at all.
The app worked on every laptop and died on its first Docker deploy with Connection refused. The database was running. The app was knocking on the wrong door.
Refused vs Timed Out
A connection starts with a SYN. If something is listening, it answers SYN-ACK. If the host is up but nothing listens on that port, it answers with RST at once, and Java throws Connection refused. If nothing answers at all, you get connect timed out instead.
compare.txtTEXT
1
2
Connection refused -> host replied RST: nothing listening
connect timed out -> no reply: firewall drop, wrong IP, host down
🎯 Key Takeaway
Refused = fast and definite.
localhost in Docker
Each container has its own network namespace, so localhost points at the container itself. Use the other container's service name.
Test the exact host and port the app uses, from the machine or container the app runs in. Then see what the server listens on.
check.shBASH
1
2
3
4
nc -vz db 5432 # from the app container
ss -ltnp | grep 5432 # on the server
# LISTEN127.0.0.1:5432 <- local only
# LISTEN0.0.0.0:5432 <- all interfaces
🎯 Key Takeaway
Test where the app runs.
Fix the Address or the Listener
Point the app at the right host and port, or make the server listen on an interface the app can reach (for Postgres, listen_addresses), then restart it.
postgresql.confTEXT
1
listen_addresses = '*' # or a specific interface
🎯 Key Takeaway
Fix where it listens, or where you knock.
● Production incidentPOST-MORTEMseverity: high
localhost Meant the Container
Symptom
java.net.ConnectException: Connection refused connecting to localhost:5432 on every start.
Assumption
The team assumed the database container was down, and restarted it twice.
Root cause
Inside the app container, localhost is the app container. Postgres was in another container, so nothing listened on the app container's port 5432.
Fix
Set DB_HOST=db (the compose service name) and added depends_on with a healthcheck.
Key lesson
localhost isn't shared between containers.
Check from where the app runs.
Refused is an address problem, not a timeout.
Production debug guideRun them from the app's side3 entries
Symptom · 01
Refused in Docker only
→
Fix
Replace localhost with the service or host name.
Symptom · 02
Works on the server, refused from elsewhere
→
Fix
ss -ltnp: the server may listen on 127.0.0.1 only.
Symptom · 03
Refused right after deploy, then fine
→
Fix
Startup order: wait for the dependency to be ready.