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 by ConnectionPool.__init__ when cache_config or cache is supplied but the protocol is not RESP3 (check_protocol_version returns False). Client-side caching (CSC) relies on RESP3 TRACKING-style invalidation push messages, so it cannot run over RESP2. protocol None/SENTINEL resolves to DEFAULT_RESP_VERSION before the check.

Solutions

Set protocol=3 (or omit it, since RESP3 is default) whenever cache_config or cache is provided.
If RESP2 is mandatory, remove cache_config/cache.
Validate check_protocol_version(protocol, 3) before building the pool when caching is desired.

Example fix

# before
pool = ConnectionPool(protocol=2, cache_config={})
# after
pool = ConnectionPool(protocol=3, cache_config={})

Defensive patterns

Strategy: validation

Validate before calling

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 RESP3 (protocol=3)')

pool = ConnectionPool(protocol=protocol, cache_config=cache_config, cache=cache)

Type guard

from redis.utils import check_protocol_version

def caching_compatible(protocol, cache_config, cache) -> bool:
    wants_cache = bool(cache_config or cache)
    return (not wants_cache) or check_protocol_version(protocol, 3)

Try / catch

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

Prevention

Use protocol=3 (the default) whenever enabling cache_config/cache.
Validate protocol before constructing the pool.
Avoid global protocol=2 test pins when caching is in use.

When it happens

Trigger: Constructing a client with protocol=2 and cache_config={...} or cache=SomeCache(). Also passing protocol='2' or a non-numeric protocol string with caching enabled.

Common situations: Forcing RESP2 for legacy response shapes while trying to use client-side caching. Test matrices that pin protocol=2 globally. Copy-pasting a cache_config without setting protocol=3.

Related errors

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

Appendix: source

Thrown at redis/connection.py:3029

        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 6a6b581b48)