ClickHouse DB::Exception: Unknown protocol

The "DB::Exception: Unknown protocol" error in ClickHouse is raised when the server receives data that does not conform to any recognized communication protocol. The error code is UNKNOWN_PROTOCOL. This typically happens when a non-ClickHouse client or tool connects to a ClickHouse port and sends data the server cannot parse as either the native binary protocol or HTTP.

Impact

The connection in question is rejected immediately. The server itself remains healthy and continues to serve other connections. However, if this error appears repeatedly, it may indicate a misconfigured application or a security scan targeting your ClickHouse ports.

Common Causes

1. A non-ClickHouse application or service accidentally connecting to a ClickHouse port.
2. A health check probe sending raw TCP data or an unsupported protocol to a ClickHouse port.
3. A monitoring tool or port scanner connecting and sending data that ClickHouse cannot interpret.
4. Connecting a MySQL or PostgreSQL client to the native ClickHouse port without enabling the MySQL or PostgreSQL compatibility interface.
5. TLS handshake sent to a non-TLS port, or a plaintext connection to a TLS-only port.

Troubleshooting and Resolution Steps

1. Identify what is connecting to the ClickHouse port. Check the server error log for the source IP and port:

   grep "UNKNOWN_PROTOCOL\|Unknown protocol" /var/log/clickhouse-server/clickhouse-server.err.log
   

2. If a health check is the cause, configure it to use the appropriate protocol. For HTTP health checks, point them at port 8123:

   curl -s 'http://your-server:8123/ping'
   

3. If you need MySQL wire protocol compatibility, enable it in the server configuration and connect to the designated port:

   <mysql_port>9004</mysql_port>
   

4. For PostgreSQL wire protocol compatibility:

   <postgresql_port>9005</postgresql_port>
   

5. If TLS mismatch is the issue, ensure clients connect to the correct port. Use --secure for native TLS connections and https:// for HTTP TLS connections:

   # Plaintext native
   clickhouse-client --port 9000
   
   # TLS native
   clickhouse-client --port 9440 --secure
   

6. If the error is caused by security scans or unauthorized access attempts, consider using firewall rules to restrict which IP addresses can reach the ClickHouse ports.

Best Practices

• Restrict access to ClickHouse ports using firewall rules or security groups to only allow known, authorized clients.
• Configure health check probes to use the HTTP interface (/ping endpoint on port 8123) rather than raw TCP checks against the native port.
• Use separate ports for each protocol interface (native, HTTP, MySQL, PostgreSQL) and document them clearly.
• Monitor for recurring UNKNOWN_PROTOCOL errors as they may indicate misconfigured infrastructure or unauthorized access attempts.

Frequently Asked Questions

Q: Can I use a MySQL client to connect to ClickHouse?
A: Yes, but you must enable the MySQL compatibility interface by setting mysql_port in the server configuration. Connect the MySQL client to that specific port (default 9004), not to the native ClickHouse port.

Q: Why do I see this error from my load balancer health checks?
A: Many load balancers perform TCP health checks by opening a connection and sending a small probe. If the probe data is not valid HTTP or native protocol, ClickHouse logs this error. Switch to an HTTP health check against the /ping endpoint on port 8123.

Q: Is this error a security concern?
A: It can be. Repeated UNKNOWN_PROTOCOL errors from unknown IP addresses may indicate port scanning or unauthorized access attempts. Review the source IPs in the logs and tighten firewall rules as needed.

Q: Does this error affect server performance?
A: Individual occurrences have negligible impact. However, a high volume of such connections (e.g., from aggressive scanners) could consume resources. Firewall rules are the appropriate mitigation.