ClickHouse DB::Exception: Cannot connect to NATS

The "DB::Exception: Cannot connect to NATS" error arises when ClickHouse is unable to establish a connection to a NATS messaging server. The CANNOT_CONNECT_NATS error code is triggered during the creation of a NATS engine table or when an existing table loses its connection and cannot re-establish it.

Impact

This error stops ClickHouse from consuming or producing messages through the NATS table engine. Data ingestion from NATS subjects halts, which can cause messages to be missed if NATS is not configured with JetStream persistence. Any materialized view pipeline that depends on a NATS source table will also stop receiving new data.

Common Causes

1. The NATS server is down or not reachable from the ClickHouse host.
2. Incorrect NATS server URL, port, or protocol in the ClickHouse table settings.
3. Authentication failure — wrong token, user/password, or NKey credentials.
4. Firewall rules blocking the NATS port (default 4222).
5. TLS configuration mismatch — the NATS server requires TLS but ClickHouse is connecting in plain text.
6. The NATS server requires JetStream but JetStream is not enabled.
7. DNS resolution failure for the NATS server hostname.

Troubleshooting and Resolution Steps

1. Review the ClickHouse server log for the specific NATS connection error:

   grep -i "CANNOT_CONNECT_NATS\|NATS\|nats" /var/log/clickhouse-server/clickhouse-server.log | tail -20
   

2. Verify the NATS server is running and accessible:

   nc -zv nats-host 4222
   

3. Test the connection using the NATS CLI:

   nats server ping --server nats://nats-host:4222
   

4. If authentication is configured, test with credentials:

   nats server ping --server nats://user:password@nats-host:4222
   

5. Review the ClickHouse NATS table definition:

   CREATE TABLE nats_table
   (
       data String
   )
   ENGINE = NATS
   SETTINGS
       nats_url = 'nats-host:4222',
       nats_subjects = 'my.subject',
       nats_format = 'JSONEachRow',
       nats_username = 'user',
       nats_password = 'pass';
   

6. For TLS connections, add the secure setting:

   SETTINGS
       nats_url = 'nats-host:4222',
       nats_secure = 1;
   

7. Check NATS server logs for connection rejection details:

   journalctl -u nats-server --no-pager | tail -20
   

Best Practices

• Use NATS JetStream for durable message delivery so messages are not lost during ClickHouse restarts or connection interruptions.
• Configure dedicated NATS credentials for ClickHouse with permissions limited to the required subjects.
• Enable TLS for NATS connections in production.
• Monitor NATS server connections and subscription counts to detect issues before they affect data ingestion.
• Test NATS connectivity from the ClickHouse host using the NATS CLI before creating engine tables.
• Set up a materialized view on the NATS table to persist ingested messages into a MergeTree table for durability.

Frequently Asked Questions

Q: Does ClickHouse support NATS JetStream?
A: Yes, ClickHouse can consume from NATS JetStream subjects. Make sure JetStream is enabled on the NATS server and the appropriate stream and consumer configurations are in place.

Q: Will ClickHouse automatically reconnect to NATS after a transient failure?
A: Yes, the NATS engine includes reconnection logic. After a connection loss, ClickHouse will attempt to reconnect periodically. Persistent configuration errors will cause repeated failures.

Q: What happens to messages published while ClickHouse is disconnected?
A: With core NATS (without JetStream), messages published while ClickHouse is disconnected are lost. With JetStream, messages are persisted and ClickHouse can consume them after reconnecting, depending on the consumer configuration.

Q: Can ClickHouse connect to a NATS cluster?
A: ClickHouse connects to a single NATS URL. For high availability, place a load balancer in front of the NATS cluster or use the NATS cluster's built-in client connection routing.