Java ConnectException — What It Means & How to Fix It

What Does This Error Mean?

A ConnectException with the message 'Connection refused' means your Java program tried to connect to a server, but nothing at that address and port accepted the connection. Either the server is not running, it is running on a different port, or a firewall is blocking the connection. This is one of the most common network errors in Java applications.

Affected Models

Java 8
Java 11
Java 17
Java 21
All Java versions

Common Causes

The server or service you are connecting to is not running at all
The server is running but on a different port number than the one your code is using
A firewall (on the server, client, or network) is blocking the connection to that port
The hostname or IP address in your code is wrong — pointing to the wrong server
The server is running but has not yet finished starting up — you connected too early

How to Fix It

Verify the server is actually running. If it is a local service, check your process list or service manager. If it is remote, try to reach it from another tool like curl or telnet.

Example test: telnet hostname port — if it connects, Java can too. If telnet fails, the problem is the server or firewall, not your Java code.
Double-check the host and port in your code. Confirm the exact hostname (or IP address) and the exact port number. Even a one-digit error in the port causes connection refused.

Print the values just before the connection: System.out.println('Connecting to ' + host + ':' + port); — this confirms what your code is actually using.
Check firewall rules on both the client and server. On Linux: sudo ufw status or sudo iptables -L. On Windows: check Windows Defender Firewall settings. The server port must be open for inbound connections.

Cloud servers (AWS, Azure, GCP) have security groups or network security rules in addition to the OS firewall. Both must allow the traffic.
If the server starts slowly (like a database or application server), add retry logic with a delay. Try connecting, catch ConnectException, wait a few seconds, and retry up to a maximum number of attempts.

This is especially useful in containerized environments (Docker, Kubernetes) where your Java app may start before the dependent service is ready.
Set a connection timeout to avoid hanging indefinitely: socket.connect(new InetSocketAddress(host, port), 5000) waits at most 5 seconds before giving up. Without a timeout, the attempt may hang for minutes.

For HTTP clients, set connection timeout on the client: HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build()

When to Call a Professional

ConnectException is usually an environment or configuration issue rather than a code bug. Verify the server is running and accessible from your machine before debugging your code. Check address, port, and firewall rules as a first step.

Frequently Asked Questions

What is the difference between Connection refused and Connection timed out?

Connection refused means something at that address actively rejected the connection — usually because nothing is listening on that port. Connection timed out means the connection attempt got no response at all within the timeout period — usually a firewall silently dropping packets rather than rejecting them. Refused is a faster, cleaner error. Timed out means you waited the full timeout duration before failing.

My code works on my machine but fails in production — why?

This is almost always a configuration or network difference between environments. In production, the server address or port may be different, or a firewall may block connections that are allowed on your local machine. Use environment variables or config files for connection settings rather than hardcoding them, so you can set different values per environment.

How do I test if a port is open without writing Java code?

Use telnet: telnet hostname port — a successful connection means the port is open and accepting connections. Or use nc (netcat): nc -zv hostname port. On Windows, use Test-NetConnection -ComputerName hostname -Port portNumber in PowerShell. If these tools can connect but Java cannot, the problem is in your Java code. If they also fail, the problem is the server or network.