langchain-ai/langgraph · error · RuntimeError

Cache is only available server-side within the LangGraph…

Error message

Cache is only available server-side within the LangGraph Agent Server (https://docs.langchain.com/langgraph/deployments).

What it means

Environment guard in the cache helpers: cache_get/cache_set work by calling runtime hooks that the LangGraph Agent Server injects at startup. When the code runs outside Agent Server (plain Python, tests, local scripts) the hook is None and this RuntimeError fires to say the server-side cache is unavailable.

Solutions

1. Move the caching code so it executes inside a LangGraph Agent Server deployment (requires runtime >= 0.7.29)
2. Guard the call, e.g. only use cache_get/cache_set when the code runs server-side, and provide a local no-op or dict-based fallback
3. Skip the cache path in local development and tests

When it happens

Trigger: Thrown at libs/sdk-py/langgraph_sdk/cache.py:67 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/e08a7653eb1eaeb0. Report an issue: GitHub.

Appendix: source

Thrown at libs/sdk-py/langgraph_sdk/cache.py:67

__all__ = [
    "SWRResult",
    "cache_get",
    "cache_set",
    "swr",
]


async def cache_get(key: str) -> Any | None:
    """Get a value from the cache.

    Returns the deserialized value, or ``None`` if the key is missing or expired.

    Requires Agent Server runtime version 0.7.29 or later.
    """
    if _cache_get is None:
        raise RuntimeError(
            "Cache is only available server-side within the LangGraph Agent Server "
            "(https://docs.langchain.com/langsmith/deployments)."
        )
    return await _cache_get(key)


async def cache_set(key: str, value: Any, *, ttl: timedelta | None = None) -> None:
    """Set a value in the cache.

    Args:
        key: The cache key.
        value: The value to cache (must be JSON-serializable).
        ttl: Optional time-to-live. Capped at 1 day; ``None`` or zero
            defaults to 1 day.

    Requires Agent Server runtime version 0.7.29 or later.
    """
    if _cache_set is None:

View on GitHub (pinned to 38031739e5)