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 a RedisError by ConnectionPool.__init__ (connection.py:3012-3014) when cache_config or cache is set but the protocol is not RESP3 (check_protocol_version returns False). Client-side caching (CSC) relies on RESP3 invalidation push messages, so it is fundamentally unavailable over RESP2.

Source

Thrown at redis/connection.py:3014

        if is_unix_domain_socket_connection or not supports_maint_notifications:
            if (
                maint_notifications_config
                and maint_notifications_config.enabled is True
            ):
                raise RedisError(
                    "Maintenance notifications are not supported with "
                    f"{connection_class}"
                )
            maint_notifications_config = MaintNotificationsConfig(enabled=False)

        self._event_dispatcher = self._connection_kwargs.get("event_dispatcher", None)
        if self._event_dispatcher is None:
            self._event_dispatcher = EventDispatcher()

        if connection_kwargs.get("cache_config") or connection_kwargs.get("cache"):
            if not check_protocol_version(self._connection_kwargs.get("protocol"), 3):
                raise RedisError("Client caching is only supported with RESP version 3")

            cache = self._connection_kwargs.get("cache")

            if cache is not None:
                if not isinstance(cache, CacheInterface):
                    raise ValueError("Cache must implement CacheInterface")

                self.cache = cache
            else:
                if self._cache_factory is not None:
                    self.cache = CacheProxy(self._cache_factory.get_cache())
                else:
                    self.cache = CacheFactory(
                        self._connection_kwargs.get("cache_config")
                    ).get_cache()

            init_csc_items()
            register_csc_items_callback(

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Set protocol=3 (or omit it for the RESP3 default) when enabling client-side caching.
2. If RESP2 is required, remove cache_config/cache — client-side caching is not supported.
3. Ensure the Redis server is >= 6 for RESP3 and tracking support.

Example fix

# before
client = redis.Redis(protocol=2, cache_config=CacheConfig())

# after
client = redis.Redis(protocol=3, cache_config=CacheConfig())

from redis.utils import check_protocol_version

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

client = redis.Redis(protocol=protocol, cache_config=cache_config, cache=cache)

def csc_compatible(protocol) -> bool:
    from redis.utils import check_protocol_version
    return check_protocol_version(protocol, 3)

from redis.exceptions import RedisError
try:
    client = redis.Redis(protocol=protocol, cache_config=cfg)
except RedisError as e:
    if "only supported with RESP version 3" in str(e):
        client = redis.Redis(protocol=3, cache_config=cfg)
    else:
        raise

When it happens

Trigger: Constructing a client with cache_config=... or cache=... while protocol=2. As with maintenance notifications, protocol=None/SENTINEL defaults to RESP3 (DEFAULT_RESP_VERSION=3), so this requires explicitly opting into RESP2.

Common situations: Forcing protocol=2 for legacy server compatibility while also configuring client-side caching; copying a CSC-enabled config into a deployment pinned to RESP2; testing CSC against an older Redis that only does RESP2.

Related errors

• Cannot retrieve information about server version
• Maintenance notifications handlers on connection are only su
• Cache must implement CacheInterface
• Maintenance notifications handlers on connection are only su
• Maintenance notifications are only supported with RESP versi

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