redis/redis-py · warning · ValueError

Given entry does not belong to the cache

Error message

Given entry does not belong to the cache

What it means

Raised as ValueError in LRUPolicy.touch when the given cache_key is not present in the cache collection. touch() is meant to mark an existing entry as recently used by calling move_to_end; if the key is absent there is nothing to move, so it refuses.

Solutions

1. Check cache.get(key) is not None before calling touch(key).
2. Catch ValueError around touch if the access pattern tolerates missing keys.
3. Avoid touching keys that may have been evicted under LRU pressure.

Example fix

# before
policy.touch(key)  # ValueError if evicted
# after
if cache.get(key) is not None:
    policy.touch(key)

if cache.get(key) is not None:
    policy.touch(key)

try:
    policy.touch(key)
except ValueError as e:
    if "does not belong" in str(e):
        pass  # already evicted; ignore
    else:
        raise

When it happens

Trigger: Calling eviction_policy.touch(key) for a key that was never inserted, was already evicted, or was deleted. This path runs during CSC access patterns that promote recently-used entries.

Common situations: A stale key reference after eviction/flush. Concurrent eviction removing the key between a get and a touch. Using touch on a freshly created policy not yet associated with populated cache entries.

Related errors

• Evictions count is above cache size
• Eviction policy should be associated with valid cache.
• Cache must implement CacheInterface
• Cannot create cache key.
• Prefix can only be used with bcast

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

Appendix: source

Thrown at redis/cache.py:343

    def evict_many(self, count: int) -> List[CacheKey]:
        self._assert_cache()
        if count > len(self._cache.collection):
            raise ValueError("Evictions count is above cache size")

        popped_keys = []

        for _ in range(count):
            popped_entry = self._cache.collection.popitem(last=False)
            popped_keys.append(popped_entry[0])

        return popped_keys

    def touch(self, cache_key: CacheKey) -> None:
        self._assert_cache()

        if self._cache.collection.get(cache_key) is None:
            raise ValueError("Given entry does not belong to the cache")

        self._cache.collection.move_to_end(cache_key)

    def _assert_cache(self):
        if self.cache is None or not isinstance(self.cache, CacheInterface):
            raise ValueError("Eviction policy should be associated with valid cache.")


class EvictionPolicy(Enum):
    LRU = LRUPolicy


class CacheConfig(CacheConfigurationInterface):
    DEFAULT_CACHE_CLASS = DefaultCache
    DEFAULT_EVICTION_POLICY = EvictionPolicy.LRU
    DEFAULT_MAX_SIZE = 10000

    DEFAULT_ALLOW_LIST = [

View on GitHub (pinned to 6a6b581b48)