{"id":"322e5e669226b41e","repo":"redis/redis-py","slug":"cache-must-implement-cacheinterface","errorCode":null,"errorMessage":"Cache must implement CacheInterface","messagePattern":"Cache must implement CacheInterface","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"redis/connection.py","lineNumber":3020,"sourceCode":"                raise RedisError(\n                    \"Maintenance notifications are not supported with \"\n                    f\"{connection_class}\"\n                )\n            maint_notifications_config = MaintNotificationsConfig(enabled=False)\n\n        self._event_dispatcher = self._connection_kwargs.get(\"event_dispatcher\", None)\n        if self._event_dispatcher is None:\n            self._event_dispatcher = EventDispatcher()\n\n        if connection_kwargs.get(\"cache_config\") or connection_kwargs.get(\"cache\"):\n            if not check_protocol_version(self._connection_kwargs.get(\"protocol\"), 3):\n                raise RedisError(\"Client caching is only supported with RESP version 3\")\n\n            cache = self._connection_kwargs.get(\"cache\")\n\n            if cache is not None:\n                if not isinstance(cache, CacheInterface):\n                    raise ValueError(\"Cache must implement CacheInterface\")\n\n                self.cache = cache\n            else:\n                if self._cache_factory is not None:\n                    self.cache = CacheProxy(self._cache_factory.get_cache())\n                else:\n                    self.cache = CacheFactory(\n                        self._connection_kwargs.get(\"cache_config\")\n                    ).get_cache()\n\n            init_csc_items()\n            register_csc_items_callback(\n                callback=lambda: self.cache.size,\n                pool_name=get_pool_name(self),\n            )\n\n        connection_kwargs.pop(\"cache\", None)\n        connection_kwargs.pop(\"cache_config\", None)","sourceCodeStart":3002,"sourceCodeEnd":3038,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/connection.py#L3002-L3038","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"# before\nclient = redis.Redis(protocol=3, cache=my_plain_dict)\n\n# after\nfrom redis.cache import CacheConfig\ncient = redis.Redis(protocol=3, cache_config=CacheConfig())\n# or wrap your store to implement CacheInterface","handlingStrategy":"type-guard","validationCode":"from redis.cache import CacheInterface\n\ndef validated_cache(c):\n    if c is not None and not isinstance(c, CacheInterface):\n        raise TypeError(\"cache must implement CacheInterface; use cache_config= instead\")\n    return c\n\nclient = redis.Redis(protocol=3, cache=validated_cache(my_cache))","typeGuard":"from redis.cache import CacheInterface\ndef is_cache_interface(c) -> bool:\n    return isinstance(c, CacheInterface)","tryCatchPattern":"try:\n    client = redis.Redis(protocol=3, cache=my_cache)\nexcept ValueError as e:\n    if \"CacheInterface\" in str(e):\n        from redis.cache import CacheConfig\n        client = redis.Redis(protocol=3, cache_config=CacheConfig())\n    else:\n        raise","preventionTips":["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."],"tags":["client-side-caching","validation","configuration","types"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}