What causes "Cache must implement CacheInterface" in redis/redis-py?

Pass an object that implements redis.cache.CacheInterface, or use the built-in cache via cache_config=CacheConfig() instead of cache=.

redis/redis-py · error · ValueError

Cache must implement CacheInterface

Error message

Cache must implement CacheInterface

What it means

Raised as a ValueError by ConnectionPool.__init__ (connection.py:3018-3020) when the cache object provided via the cache= kwarg is not an instance of CacheInterface. The library needs a cache that implements the required get/set/delete/flush contract so it can wire invalidation handling.

Source

Thrown at redis/connection.py:3020

                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(
                callback=lambda: self.cache.size,
                pool_name=get_pool_name(self),
            )

        connection_kwargs.pop("cache", None)
        connection_kwargs.pop("cache_config", None)

View on GitHub (pinned to da03cdc7e8)

Solutions

Pass an object that implements redis.cache.CacheInterface, or use the built-in cache via cache_config=CacheConfig() instead of cache=.
If using a custom cache, subclass/adapt it to CacheInterface (implement the required methods: get, set, delete, flush, etc.).
Prefer cache_factory / cache_config which construct a compliant cache for you.

Example fix

# before
client = redis.Redis(protocol=3, cache=my_plain_dict)

# after
from redis.cache import CacheConfig
cient = redis.Redis(protocol=3, cache_config=CacheConfig())
# or wrap your store to implement CacheInterface

Defensive patterns

Strategy: type-guard

Validate before calling

from redis.cache import CacheInterface

def validated_cache(c):
    if c is not None and not isinstance(c, CacheInterface):
        raise TypeError("cache must implement CacheInterface; use cache_config= instead")
    return c

client = redis.Redis(protocol=3, cache=validated_cache(my_cache))

Type guard

from redis.cache import CacheInterface
def is_cache_interface(c) -> bool:
    return isinstance(c, CacheInterface)

Try / catch

try:
    client = redis.Redis(protocol=3, cache=my_cache)
except ValueError as e:
    if "CacheInterface" in str(e):
        from redis.cache import CacheConfig
        client = redis.Redis(protocol=3, cache_config=CacheConfig())
    else:
        raise

Prevention

Prefer cache_config / cache_factory over passing a raw cache object.
Wrap third-party caches in a CacheInterface adapter with tests.
Add an isinstance(cache, CacheInterface) assertion in a config-validation step.

When it happens

Trigger: Passing cache=some_dict, cache=my_lru_lib_instance, or any custom object that does not implement CacheInterface to ConnectionPool/Redis while also being on RESP3 (otherwise error 414 fires first).

Common situations: Plugging in a third-party cache (cachetools, functools.lru_cache, diskcache) without wrapping it; passing a raw dict by mistake; partially implementing a custom cache class and missing required methods.

Related errors

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