Error log: “ConnectTimeoutException” – The connection that never was

Error log: Like SocketTimeoutException, this error will not appear in your OpenSearch logs. It happens in your client application’s logs before a connection is even established.

None
java.net.ConnectException: Connection timed out

Or (depending on the client):

None
org.opensearch.client.transport.ConnectTimeoutException: 

  Connect timeout retrieving node versions

Why… is this happening? This is a pure, low-level network connection failure. It is different from a SocketTimeoutException (Blog #32), which happens after a connection is made, while waiting for data.

A ConnectTimeoutException means your client tried to open a new network connection (a “socket”) to the OpenSearch node’s IP and port (e.g., 10.1.2.3:9200), and it failed to even get a response within the allowed timeout (often just a few seconds).

Common causes:

1. Firewall / security group: This is the #1 cause. A firewall (on the client, on the server, or in the network) is dropping the connection packets. The client sends a “hello?” packet (a SYN packet) and never gets a reply, so it times out.
2. OpenSearch is down: The OpenSearch process on that specific node is not running, so nothing is listening on port 9200.
3. Incorrect IP or Port: Your client is configured with the wrong IP address or port for your OpenSearch cluster.
4. Network routing issue: A network misconfiguration (e.g., bad subnet route) is preventing your client’s packets from ever reaching the server.

Note: This is different from a “Connection Refused” error. “Connection Refused” is an active rejection (the server’s OS is reachable, but the port is closed). “Connection Timed Out” is a passive failure—your packets are going into a black hole.

Best Practice:

1. Test with telnet or nc: From the exact same machine that your client is running on, use a low-level tool to test the connection.
Bash

None
# This will try to connect to port 9200

telnet 10.1.2.3 9200

2. If this telnet command just hangs and then says “Connection timed out,” you have confirmed it’s a network/firewall problem.

3. Check all firewalls:

• Server firewall: Check iptables or firewalld on the OpenSearch node.
• Cloud security group: Check the inbound rules for your OpenSearch node’s Security Group (e.g., in AWS, Azure, GCP). Does it allow traffic on port 9200 from your client’s IP?
• Client firewall: Check the outbound rules on your client’s machine.

4. Verify the opensearch.hosts Config: Double-check the IP addresses and ports in your client’s configuration.

What else can I do? Network debugging can be frustrating. If telnet fails, it’s time to talk to your network or cloud engineering team. Show them the telnet failure and ask them to trace the path from the client to the server. For general questions, contact us in The OpenSearch Slack Channel in #General.