Fixing 'java.net.ConnectException: Connection refused' in Java Applications

The Error

You’ve likely seen it: you are ready to test a new REST endpoint or database connection, but Java throws a wall of text at you instead. This specific exception usually looks like this:

java.net.ConnectException: Connection refused (Connection refused)
    at java.base/sun.nio.ch.Net.connect0(Native Method)
    at java.base/sun.nio.ch.Net.connect(Net.java:579)
    at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:585)
    at java.base/java.net.Socket.connect(Socket.java:633)
    at java.base/java.net.Socket.<init>(Socket.java:507)

What it actually means

This error is blunt. Your client successfully reached the destination server, but that server actively said "No." Unlike a Connection Timeout, where the server simply ignores you, a Connection Refused means the OS replied with a TCP RST (Reset) packet.

Essentially, the door is there, but it is locked and nobody is home.

Common Causes and Fixes

1. The Target Service is Not Running

This is the most common culprit. You might be trying to hit a microservice on port 8080, but you forgot to run mvn spring-boot:run. If the process isn't active, the OS has nothing to hand the connection to.

The Fix: Verify the service is actually listening. Run these commands on the server:

# Check if anything is listening on port 8080 (Linux/macOS)
sudo lsof -i :8080

# Or use netstat on Windows
netstat -ano | findstr :8080

If these commands return an empty result, start your application.

2. Port Mismatch

It is easy to mix up ports when managing multiple services. Your server might be running on port 9000, but your client is still hardcoded to look for the default 8080. This often happens after a configuration change in application.properties that didn't get synced to the frontend.

The Fix: Open your configuration files side-by-side. Ensure the server.port in your backend matches the BASE_URL in your client code exactly.

3. The "Localhost" Trap (Binding Issues)

This is a classic headache for developers moving from local testing to Docker or production. If your server binds to 127.0.0.1, it only listens to itself. If a client tries to connect via the server's LAN IP (like 192.168.1.50), the OS will refuse it.

The Fix: Configure your server to bind to 0.0.0.0. This tells the application to listen on all available network interfaces.

// Java ServerSocket example: bind to all interfaces
ServerSocket server = new ServerSocket(8080, 50, InetAddress.getByName("0.0.0.0"));

In Spring Boot, simply add server.address=0.0.0.0 to your properties file.

4. Firewalls and Cloud Security Groups

Sometimes the service is running perfectly, but a security layer is standing in the way. While many firewalls silently "drop" packets (causing timeouts), some are configured to "reject" them. This is common with local ufw settings or AWS Security Groups.

The Fix: Check your firewall rules. On a Linux server, you can quickly test by opening the port:

# Allow traffic on port 8080 via UFW
sudo ufw allow 8080/tcp

5. Connection Backlog is Full

Under heavy load, a server might stop accepting new connections. Java's ServerSocket has a default "backlog"—a queue for pending connections. If this queue (often defaulting to 50) fills up because the server is too slow, the OS starts refusing new requests.

The Fix: Increase the backlog size or, better yet, optimize your request handling logic to clear the queue faster.

How to Verify the Fix

Don't waste time restarting your heavy Java app until you know the port is open. Use lightweight tools to probe the connection first.

Using Netcat (nc):

nc -zv 192.168.1.50 8080

A "Connection to 192.168.1.50 port 8080 [tcp/http] succeeded!" message means your network path is finally clear.

Personal Tips from the Field

When I'm debugging complex microservice grids, I often find that IP range issues are the silent killer. I use this Subnet Calculator to double-check that my CIDR blocks and 0.0.0.0 bindings actually make sense for the network I'm deploying on.

One more thing: always log the target URI in your catch block. Seeing Failed to connect to 127.0.0.1:8080 in a production log is a massive time-saver. It immediately tells you that your app is trying to talk to itself instead of the production database.

try {
    // your connection logic here
} catch (ConnectException e) {
    logger.error("Connection refused to {}:{}", remoteHost, remotePort);
    throw e;
}