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 in `RedisCluster.__init__` when `cache_config` or `cache` is supplied but the negotiated protocol is not RESP3. Client-side caching (the tracking + invalidation mechanism) requires Redis RESP3 push notifications, so enabling a cache with protocol < 3 is rejected with RedisError rather than silently degrading.

Source

Thrown at redis/cluster.py:887

        kwargs = cleanup_kwargs(**kwargs)
        if retry:
            self.retry = retry
        else:
            self.retry = Retry(
                backoff=ExponentialWithJitterBackoff(
                    base=DEFAULT_RETRY_BASE, cap=DEFAULT_RETRY_CAP
                ),
                retries=cluster_error_retry_attempts,
            )

        self.encoder = Encoder(
            kwargs.get("encoding", "utf-8"),
            kwargs.get("encoding_errors", "strict"),
            kwargs.get("decode_responses", False),
        )
        protocol = kwargs.get("protocol", None)
        if (cache_config or cache) and not check_protocol_version(protocol, 3):
            raise RedisError("Client caching is only supported with RESP version 3")

        if (
            maint_notifications_config
            and maint_notifications_config.enabled
            and not check_protocol_version(protocol, 3)
        ):
            raise RedisError(
                "Maintenance notifications are only supported with RESP version 3"
            )
        if check_protocol_version(protocol, 3) and maint_notifications_config is None:
            maint_notifications_config = MaintNotificationsConfig()

        # Build the client-level HIMPORT registry once (always empty at construction)
        # and share the same object with every node pool, so the fieldset registry is
        # shared cluster-wide and runtime himport_prepare mutates one object. It is
        # handed to the NodesManager and injected onto each node's pool in
        # create_redis_node; it is deliberately NOT forwarded through connection_kwargs,
        # so nodes reuse the one shared object rather than each rebuilding their own.

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Set `protocol=3` (and ensure the server is Redis >= 6 with RESP3 support) when using client caching.
2. If the server cannot do RESP3, remove `cache_config`/`cache` from the constructor.
3. Upgrade the Redis server to a version that supports RESP3 if you need client-side caching.

Example fix

# before
rc = RedisCluster(host='h', port=7000, protocol=2, cache_config=CacheConfig())  # raises

# after
rc = RedisCluster(host='h', port=7000, protocol=3, cache_config=CacheConfig())

protocol = kwargs.get('protocol', 3)
if (cache_config or cache) and protocol != 3:
    raise ValueError('Client-side caching requires RESP3 (protocol=3)')

def cache_protocol_compatible(protocol, cache_config, cache) -> bool:
    return (cache_config is None and cache is None) or protocol == 3

When it happens

Trigger: Constructing `RedisCluster(cache_config=CacheConfig(...), protocol=2)` or omitting protocol (which must then default to 3) while requesting a cache. The check `not check_protocol_version(protocol, 3)` triggers when RESP3 is not in effect.

Common situations: Forcing `protocol=2` for compatibility with an older server while still trying to use client caching; supplying a default `CacheConfig` without also setting `protocol=3`; talking to a Redis < 6 (no RESP3) and enabling caching.

Related errors

• Maintenance notifications are only supported with hiredis an
• Maintenance notifications are only supported with RESP versi
• Maintenance notifications are only supported with hiredis an
• Maintenance notifications handlers on connection are only su
• Maintenance notifications handlers on connection are only su

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