langchain-ai/langgraph · error · ValueError

Key does not start with prefix

Error message

Key {redis_key} does not start with prefix {prefix}

What it means

Internal consistency check in RedisCache._parse_key: when decoding a key read back from Redis, the stored key does not begin with the cache's configured prefix. Because _make_key always builds keys as prefix + namespace + ':' + key, this indicates the cache entry was written by a different prefix configuration (or a foreign key collided in the same Redis database) and the namespace/key tuple cannot be recovered safely.

Solutions

1. Use the same prefix for writes and reads of a given cache; initialize RedisCache with a stable, unique prefix per deployment
2. Flush stale keys (SCAN + DEL by old prefix) after changing the prefix so old entries are not parsed
3. Give each environment/application its own Redis logical database or prefix to avoid cross-contamination

When it happens

Trigger: Thrown at libs/checkpoint/langgraph/cache/redis/__init__.py:39 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of langchain-ai/langgraph@38031739e5 (2026-08-26). Data as JSON: /api/errors/cb641f442e0f7c0f. Report an issue: GitHub.

Appendix: source

Thrown at libs/checkpoint/langgraph/cache/redis/__init__.py:39

        Args:
            redis: Redis client instance (sync or async)
            serde: Serializer to use for values
            prefix: Key prefix for all cached values
        """
        super().__init__(serde=serde)
        self.redis = redis
        self.prefix = prefix

    def _make_key(self, ns: Namespace, key: str) -> str:
        """Create a Redis key from namespace and key."""
        ns_str = ":".join(ns) if ns else ""
        return f"{self.prefix}{ns_str}:{key}" if ns_str else f"{self.prefix}{key}"

    def _parse_key(self, redis_key: str) -> tuple[Namespace, str]:
        """Parse a Redis key back to namespace and key."""
        if not redis_key.startswith(self.prefix):
            raise ValueError(
                f"Key {redis_key} does not start with prefix {self.prefix}"
            )

        remaining = redis_key[len(self.prefix) :]
        if ":" in remaining:
            parts = remaining.split(":")
            key = parts[-1]
            ns_parts = parts[:-1]
            return (tuple(ns_parts), key)
        else:
            return (tuple(), remaining)

    def get(self, keys: Sequence[FullKey]) -> dict[FullKey, ValueT]:
        """Get the cached values for the given keys."""
        if not keys:
            return {}

        # Build Redis keys

View on GitHub (pinned to 38031739e5)