redis/redis-py · error · RedisError

Client caching is only supported with RESP version 3

Error message

Client caching is only supported with RESP version 3

What it means

Raised as RedisError during Redis.__init__ when client-side caching (cache_config or cache) is provided but the connection pool protocol is not RESP3. Client-side caching depends on RESP3 push notifications (invalidation messages), so it cannot function under RESP2. The check at client.py:524-527 runs after the pool is created, reading the pool's resolved protocol.

Solutions

1. Set protocol=3 when configuring client-side caching.
2. Drop cache_config/cache if you must remain on RESP2.
3. Ensure the Redis server is 6+ and supports RESP3 invalidation.

Example fix

# before
r = Redis(cache_config=CacheConfig(), protocol=2)  # RedisError
# after
r = Redis(cache_config=CacheConfig(), protocol=3)

if (cache_config or cache) and protocol not in (3, "3"):
    raise ValueError("client-side caching requires protocol=3")

When it happens

Trigger: Constructing Redis(cache_config=CacheConfig(), protocol=2) or with the default resolving to non-3. The check fires after the connection pool is built and its protocol queried.

Common situations: Enabling CSC while pinned to RESP2 for legacy response shapes. Passing cache_config without also setting protocol=3. Migrating to CSC on a server/client config that defaults to RESP2.

Related errors

• Cannot retrieve information about server version
• Client caching is only supported with RESP version 3
• Maintenance notifications handlers on connection are only…
• Cache must implement CacheInterface
• Client caching is only supported with RESP version 3

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/6c1e728f31adca6d. Report an issue: GitHub.

Appendix: source

Thrown at redis/client.py:527

                AfterPooledConnectionsInstantiationEvent(
                    [connection_pool], ClientType.SYNC, credential_provider
                )
            )
            self.auto_close_connection_pool = True
        else:
            self.auto_close_connection_pool = False
            self._event_dispatcher.dispatch(
                AfterPooledConnectionsInstantiationEvent(
                    [connection_pool], ClientType.SYNC, credential_provider
                )
            )

        self.connection_pool = connection_pool

        if (cache_config or cache) and not check_protocol_version(
            self.connection_pool.get_protocol(), 3
        ):
            raise RedisError("Client caching is only supported with RESP version 3")

        self.single_connection_lock = threading.RLock()
        self.connection = None
        self._single_connection_client = single_connection_client
        if self._single_connection_client:
            self.connection = self.connection_pool.get_connection()
            self._event_dispatcher.dispatch(
                AfterSingleConnectionInstantiationEvent(
                    self.connection, ClientType.SYNC, self.single_connection_lock
                )
            )

        connection_kwargs = self.connection_pool.connection_kwargs
        self.response_callbacks = CaseInsensitiveDict(
            get_response_callbacks(
                user_protocol=connection_kwargs.get("protocol"),
                legacy_responses=connection_kwargs.get("legacy_responses", True),
            )

View on GitHub (pinned to 6a6b581b48)