langchain-ai/langgraph · error · ValueError

refresh_on must be 'auto' or 'heartbeat'

Error message

refresh_on must be 'auto' or 'heartbeat'

What it means

Error "refresh_on must be 'auto' or 'heartbeat'" thrown in langchain-ai/langgraph.

Source

Thrown at libs/langgraph/langgraph/types.py:505

        """Normalize a timeout value to positive-second policy fields."""
        if value is None:
            return None
        if isinstance(value, TimeoutPolicy):
            # Fast path: a policy already produced by coerce() has float
            # timeouts and a validated refresh_on, so we can return it as-is.
            # `frozen=True` makes this safe to share.
            rt, it = value.run_timeout, value.idle_timeout
            if (
                value.refresh_on in ("auto", "heartbeat")
                and (rt is None or (type(rt) is float and rt > 0))
                and (it is None or (type(it) is float and it > 0))
                and (rt is not None or it is not None)
            ):
                return value
        else:
            value = cls(run_timeout=value)
        if value.refresh_on not in ("auto", "heartbeat"):
            raise ValueError("refresh_on must be 'auto' or 'heartbeat'")
        run_timeout = _coerce_timeout_seconds(value.run_timeout, field="run_timeout")
        idle_timeout = _coerce_timeout_seconds(value.idle_timeout, field="idle_timeout")
        if run_timeout is None and idle_timeout is None:
            return None
        return cls(
            run_timeout=run_timeout,
            idle_timeout=idle_timeout,
            refresh_on=value.refresh_on,
        )


KeyFuncT = TypeVar("KeyFuncT", bound=Callable[..., str | bytes])


@dataclass(**_DC_KWARGS)
class CachePolicy(Generic[KeyFuncT]):
    """Configuration for caching nodes."""

View on GitHub (pinned to 38031739e5)

When it happens

Trigger: Thrown at libs/langgraph/langgraph/types.py:505 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/9ea03ce03295aa50. Report an issue: GitHub.