ClickHouse DB::Exception: Internal Redis error

The "DB::Exception: Internal Redis error" is raised when ClickHouse fails to communicate with a Redis server through the Redis dictionary source or the Redis table engine. The INTERNAL_REDIS_ERROR code encapsulates errors from the Redis client library, including connection failures, authentication problems, and command execution errors.

Impact

This error prevents ClickHouse from reading or writing data through Redis-backed dictionaries or tables. Dictionaries sourced from Redis will fail to load or refresh, which can cause queries that use dictGet() to either fail or return default values. Redis engine tables will become inaccessible for both reads and writes.

Common Causes

1. Redis server is not running or unreachable from the ClickHouse host.
2. Wrong hostname, port, or database index in the ClickHouse configuration.
3. Authentication failure — Redis requires a password (requirepass) but ClickHouse did not provide one, or the password is wrong.
4. Redis ACL restrictions that deny the commands ClickHouse needs to execute.
5. Network or firewall rules blocking the Redis port (default 6379).
6. Redis memory limit reached, causing write commands to fail.
7. TLS misconfiguration when connecting to a Redis instance that requires encrypted connections.
8. Data type mismatch — the Redis data structure does not match what ClickHouse expects.

Troubleshooting and Resolution Steps

1. Check the ClickHouse server log for Redis client errors:

   grep -i "INTERNAL_REDIS_ERROR\|Redis\|redis" /var/log/clickhouse-server/clickhouse-server.log | tail -20
   

2. Verify Redis is running and reachable:

   redis-cli -h redis-host -p 6379 ping
   

3. Test authentication:

   redis-cli -h redis-host -p 6379 -a your_password ping
   

4. Review the dictionary or table definition in ClickHouse:

   <dictionary>
     <source>
       <redis>
         <host>redis-host</host>
         <port>6379</port>
         <password>your_password</password>
         <db_index>0</db_index>
         <storage_type>simple</storage_type>
       </redis>
     </source>
   </dictionary>
   

5. For the Redis table engine, verify the configuration:

   CREATE TABLE redis_table
   (
       key String,
       value String
   )
   ENGINE = Redis('redis-host:6379', 0, 'your_password')
   PRIMARY KEY (key);
   

6. Check Redis memory usage if write operations are failing:

   redis-cli -h redis-host INFO memory
   

7. If using Redis ACLs (Redis 6+), ensure the user has the required command permissions:

   redis-cli -h redis-host ACL LIST
   

Best Practices

• Use a dedicated Redis user with ACL permissions limited to the commands and keys ClickHouse needs.
• Monitor Redis memory usage and configure an appropriate maxmemory policy to prevent out-of-memory errors.
• Enable Redis persistence (RDB or AOF) if the data is not easily recoverable from other sources.
• Use TLS for Redis connections in production environments, especially when Redis is accessed over untrusted networks.
• Test Redis connectivity and data access from the ClickHouse host before configuring dictionaries or tables.
• Consider using Redis Sentinel or Redis Cluster for high availability, though ClickHouse connects to a single Redis endpoint.

Frequently Asked Questions

Q: Which Redis data structures does ClickHouse support?
A: The Redis dictionary source supports simple key-value pairs (strings) and hash maps. The storage type is configured with the storage_type parameter, which can be simple or hash_map.

Q: Can ClickHouse connect to Redis Cluster?
A: ClickHouse's Redis integration connects to a single Redis node. For Redis Cluster setups, you would need to point ClickHouse to a specific node or use a proxy like Twemproxy that presents a single endpoint.

Q: Why does my Redis dictionary fail to load even though redis-cli works fine?
A: Common causes include the ClickHouse server running as a different system user that cannot resolve the Redis hostname, Redis ACLs that restrict the commands ClickHouse uses internally, or the Redis database index being different from what you tested with.

Q: Does ClickHouse cache Redis dictionary data locally?
A: Yes, dictionaries in ClickHouse are loaded into memory and refreshed periodically based on the lifetime setting. Between refreshes, ClickHouse serves data from its local cache, so transient Redis errors only affect the refresh cycle.