Home › Java › java.net.ConnectException: Connection refused — What It Means and How to Fix It
Intermediate 3 min · November 15, 2026

java.net.ConnectException: Connection refused — What It Means and How to Fix It

'Connection refused' means the host answered your connection attempt with a reset: nothing is listening on that host and port.

N
Naren Founder & Principal Engineer

20+ years shipping production Java in banking & fintech. Written from production experience, not tutorials.

Follow
✓ Production
production tested
November 15, 2026
last updated
2,132
articles · all by Naren
Before you start⏱ 6 min
  • ✓Basic Java
  • ✓Basic TCP/HTTP concepts
 ● Production Incident 🔎 Debug Guide
⚡Quick Answer
  • 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.

compose.ymlYAML
1
2
3
4
5
6
7
8
9
10
11
services:
  app:
    environment:
      DB_HOST: db
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD", "pg_isready"]
🎯 Key Takeaway
Use the service name, not localhost.

Check From the App's Side

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
# LISTEN 127.0.0.1:5432  <- local only
# LISTEN 0.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.
⚙ Quick Reference
4 commands from this guide
FileCommand / CodePurpose
compare.txtConnection refused -> host replied RST: nothing listeningRefused vs Timed Out
compose.ymlservices:localhost in Docker
check.shnc -vz db 5432 # from the app containerCheck From the App's Side
postgresql.conflisten_addresses = '*' # or a specific interfaceFix the Address or the Listener

Key takeaways

1
Refused = RST
nothing listening.
2
localhost isn't shared in Docker.
3
Check with nc and ss from the app's side.
4
Retries don't fix it.

Common mistakes to avoid

3 patterns
×

localhost inside a container

Symptom
Refused only in Docker.
Fix
Use the service name.
×

Raising timeouts or retries

Symptom
Same refusal, just slower.
Fix
Fix the address.
×

Server bound to 127.0.0.1

Symptom
Works locally on the server only.
Fix
Listen on the right interface.
INTERVIEW PREP · PRACTICE MODE

Interview Questions on This Topic

Q01SENIOR
What's the difference between Connection refused and connect timed out?
Q01 of 01SENIOR

What's the difference between Connection refused and connect timed out?

ANSWER
Refused means the host replied with RST because nothing listens; timed out means no reply arrived at all.
FAQ · 3 QUESTIONS

Frequently Asked Questions

01
What does java.net.ConnectException: Connection refused mean?
02
Why does it work locally but not in Docker?
03
Connection refused: connect on Windows?
N
Naren Founder & Principal Engineer

20+ years shipping production Java in banking & fintech. Written from production experience, not tutorials.

Follow
✓ Verified
production tested
November 15, 2026
last updated
2,132
articles · all by Naren
🔥

That's Exceptions. Mark it forged?

3 min read · try the examples if you haven't

←
Previous
java.net.SocketException: Connection Reset
10 / 11 · Exceptions
Next
java.net.SocketTimeoutException: Read Timed Out
→