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 in Redis.__init__ (redis/client.py:527) when a cache_config or cache object is provided but the connection pool's negotiated protocol is not RESP3. Client-side caching in redis-py depends on RESP3 push notifications to invalidate cache entries, so RESP2 is rejected.

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 da03cdc7e8)

Solutions

Set protocol=3 when enabling client-side caching (cache_config or cache).
Upgrade the Redis server to a RESP3-capable version (>=7.0).
Remove cache_config/cache if you must stay on RESP2.

Example fix

# before
r = Redis(host='localhost', cache_config=CacheConfig())  # protocol defaults to RESP3 but server negotiates RESP2 -> RedisError
# after
r = Redis(host='localhost', protocol=3, cache_config=CacheConfig())

Defensive patterns

Strategy: validation

Validate before calling

from redis._parsers.helpers import check_protocol_version
if (cache_config or cache) and not check_protocol_version(protocol, 3):
    raise ConfigError('Client-side caching requires protocol=3')

Type guard

def resp3_enabled(protocol) -> bool:
    from redis._parsers.helpers import check_protocol_version
    return check_protocol_version(protocol, 3)

Try / catch

try:
    r = Redis(protocol=protocol, cache_config=cache_config)
except RedisError as e:
    logger.error('need RESP3 for client caching: %s', e)
    raise

Prevention

Set protocol=3 when enabling cache_config or passing a cache.
Use a Redis >=7.0 server for client-side caching.

When it happens

Trigger: Constructing Redis(cache_config=CacheConfig(), protocol=2) (or protocol omitted against a RESP2-only server); providing a pre-built cache object while the pool protocol resolves to <3.

Common situations: Defaulting protocol while enabling client caching; connecting to a Redis <7.0 that cannot do RESP3; config template enabling cache without bumping protocol.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/6c1e728f31adca6d.json. Report an issue: GitHub.