langchain-ai/langgraph · error

Invalid state_schema: {schema}. Expected a type or Annotated

Error message

Invalid state_schema: {schema}. Expected a type or Annotated[type, reducer]. Please provide a valid schema to ensure correct updates.
 See: https://langchain-ai.github.io/langgraph/reference/graphs/#stategraph

What it means

Error "Invalid state_schema: {schema}. Expected a type or Annotated[type, reducer]. Please provide a valid schema to ensure correct updates. See: https://langchain-ai.github.io/langgraph/reference/graphs/#stategraph" thrown in langchain-ai/langgraph.

Source

Thrown at libs/langgraph/langgraph/graph/state.py:117

_DEFAULT_ERROR_HANDLER_NODE = "__default_error_handler__"


@dataclass(slots=True)
class _NodeDefaults:
    """Default node policies applied to every node at compile time."""

    retry_policy: RetryPolicy | Sequence[RetryPolicy] | None = None
    cache_policy: CachePolicy | None = None
    error_handler: StateNode[Any, Any] | None = None
    timeout: TimeoutPolicy | None = None


def _warn_invalid_state_schema(schema: type[Any] | Any) -> None:
    if isinstance(schema, type):
        return
    if typing.get_args(schema):
        return
    warnings.warn(
        f"Invalid state_schema: {schema}. Expected a type or Annotated[type, reducer]. "
        "Please provide a valid schema to ensure correct updates.\n"
        " See: https://langchain-ai.github.io/langgraph/reference/graphs/#stategraph"
    )


def _get_node_name(node: StateNode[Any, ContextT]) -> str:
    try:
        return getattr(node, "__name__", node.__class__.__name__)
    except AttributeError:
        raise TypeError(f"Unsupported node type: {type(node)}")


class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
    """A graph whose nodes communicate by reading and writing to a shared state.

    The signature of each node is `State -> Partial<State>`.

View on GitHub (pinned to 38031739e5)

When it happens

Trigger: Thrown at libs/langgraph/langgraph/graph/state.py:117 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/f3d4a1bb1d70d028. Report an issue: GitHub.