ClickHouse DB::Exception: Client connected to wrong port

The "DB::Exception: Client connected to wrong port" error in ClickHouse occurs when a client attempts to communicate using a protocol that does not match the port it has connected to. The error code is CLIENT_HAS_CONNECTED_TO_WRONG_PORT. This is one of the most common setup mistakes: connecting the native clickhouse-client to the HTTP port (8123) or sending HTTP requests to the native protocol port (9000).

Impact

The connection is immediately rejected and no queries can be executed. This is usually encountered during initial setup or configuration changes and does not affect the server's stability. However, it can be confusing for new users or when reconfiguring connection strings in applications.

Common Causes

1. Connecting clickhouse-client (native protocol) to port 8123, which is the HTTP interface.
2. Sending HTTP requests (e.g., via curl or an HTTP-based driver) to port 9000, which is the native protocol interface.
3. Using the wrong port in a connection string after a server reconfiguration or migration.
4. Load balancer or proxy routing traffic to the wrong backend port.
5. Confusing the TLS and non-TLS ports (9000 vs 9440 for native, 8123 vs 8443 for HTTP).

Troubleshooting and Resolution Steps

1. Identify which ports your ClickHouse server is using. Check the server configuration:

   <!-- Default ports in config.xml -->
   <tcp_port>9000</tcp_port>
   <http_port>8123</http_port>
   <tcp_port_secure>9440</tcp_port_secure>
   <https_port>8443</https_port>
   

2. For the native clickhouse-client, connect to the native port (default 9000):

   clickhouse-client --host your-server --port 9000
   

3. For HTTP-based tools like curl, use the HTTP port (default 8123):

   curl 'http://your-server:8123/?query=SELECT+1'
   

4. If you are using a driver or connector library, verify its documentation for the correct port. JDBC and ODBC drivers may use either the HTTP or native protocol depending on the driver implementation.

5. When using TLS, ensure the client connects to the corresponding secure port:

   # Native protocol with TLS
   clickhouse-client --host your-server --port 9440 --secure
   
   # HTTP with TLS
   curl 'https://your-server:8443/?query=SELECT+1'
   

6. If a load balancer is in play, verify that it routes traffic to the correct backend port based on the expected protocol.

Best Practices

• Document your ClickHouse port assignments clearly, especially in environments where non-default ports are used.
• Include the port number explicitly in connection strings rather than relying on defaults, to prevent confusion.
• When setting up load balancers, create separate listener/target group configurations for the native and HTTP protocols.
• Test connectivity with a simple query immediately after changing port configurations to catch mismatches early.

Frequently Asked Questions

Q: What are the default ClickHouse ports?
A: The defaults are: 9000 for native protocol, 8123 for HTTP, 9440 for native with TLS, and 8443 for HTTPS. These can be changed in the server configuration.

Q: I am using a ClickHouse JDBC driver. Which port should I use?
A: It depends on the driver. The official clickhouse-jdbc driver uses the HTTP protocol by default and should connect to port 8123 (or 8443 for HTTPS). Some alternative drivers use the native protocol on port 9000. Check your driver's documentation.

Q: Can I run both HTTP and native protocols on the same port?
A: No. Each protocol requires its own dedicated port. ClickHouse does not support protocol multiplexing on a single port.

Q: How can I tell which protocol a client library uses?
A: Check the library's documentation. Generally, libraries described as "HTTP" or "REST" clients use port 8123, while those described as "native" or "binary" clients use port 9000.