Handling java.net.ConnectException

1. Introduction

In this quick tutorial, we'll discuss some possible causes of java.net.ConnectException. Then, we'll show how to check the connection with the help of two publicly available commands and a small Java example.

2. What Causes java.net.ConnectException

The java.net.ConnectException exception is one of the most common Java exceptions related to networking. We may encounter it when we're establishing a TCP connection from a client application to a server. As it's a checked exception, we should handle it properly in our code in a try-catch block.

There are many possible causes of this exception:

• The server we are trying to connect to is simply not started, therefore, we can't obtain a connection
• The host and port combination we are using to connect to the server might be incorrect
• A firewall might block connections from specific IP addresses or ports

3. Catching the Exception Programmatically

We usually connect to the server programmatically using the java.net.Socket class. To establish a TCP connection, we must make sure we're connecting to the correct host and port combination:

String host = "localhost";
int port = 5000;

try {
    Socket clientSocket = new Socket(host, port);

    // do something with the successfully opened socket

    clientSocket.close();
} catch (ConnectException e) {
    // host and port combination not valid
    e.printStackTrace();
} catch (Exception e) {
    e.printStackTrace();
}

If the host and port combination is incorrect, Socket will throw a java.net.ConnectException. In our code example above, we print the stack trace to better determine what's going wrong. No visible stack trace means that our code successfully connected to the server.

In this case, we should check the connection details before proceeding. We should also check that our firewall isn't preventing the connection.

4. Checking Connections With the CLI

Through the CLI, we can use the ping command to check whether the server we're trying to connect to is running.

For example, we can check if the Baeldung server is started:

ping baeldung.com

If the Baeldung server is running, we should see information about sent and received packages.

PING baeldung.com (104.18.63.78): 56 data bytes
64 bytes from 104.18.63.78: icmp_seq=0 ttl=57 time=7.648 ms
64 bytes from 104.18.63.78: icmp_seq=1 ttl=57 time=14.493 ms

telnet is another useful CLI tool that we can use to connect to a specified host or IP address. Additionally, we can also pass an exact port that we want to test. Otherwise, default port 23 will be used.

For example, if we want to connect to the Baeldung website on port 80, we can run:

telnet baeldung.com 80

It's worth noting that ping and telnet commands may not always work — even if the server we're trying to reach is running and we're using the correct host and port combination. This is often the case in production systems, which are usually heavily secured to prevent unauthorized access. Besides, a firewall blocking specific internet traffic might be another cause of failure.

5. Conclusion

In this quick tutorial, we've discussed the common Java network exception, java.net.ConnectException.

We started with an explanation of possible causes of that exception. We showed how to catch the exception programmatically, along with two useful CLI commands that might help to determine the cause.

As always, the code shown in this article is available over on GitHub.