Skip to content

docs: Add warning about state schema definition in LangGraph #1881

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
arrdel wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Add warning about state schema definition in LangGraph #1881

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions src/oss/langgraph/graph-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,36 @@ The main documented way to specify the schema of a graph is by using Zod schemas
By default, the graph will have the same input and output schemas. If you want to change this, you can also specify explicit input and output schemas directly. This is useful when you have a lot of keys, and some are explicitly for input and others for output.
:::


:::warning
### Defining All State Keys

When extending a state schema (e.g., extending `AgentState` or `MessagesState`), you **must explicitly define all custom fields in your state TypedDict**. Any fields that are not declared in the schema definition will be silently ignored and not available in your graph.

Comment on lines +88 to +91
Copy link

Copilot AI Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The heading "Defining All State Keys" is positioned inside a warning callout. According to Mintlify documentation patterns and the examples found in this repository (e.g., line 58 uses <Warning> without a heading inside), warning callouts typically don't include headings. The heading structure could interfere with the document's table of contents and navigation.

Consider removing the heading and incorporating that information into the opening sentence of the warning, or restructure this as a regular section with the warning callout inside it.

Suggested change
### Defining All State Keys
When extending a state schema (e.g., extending `AgentState` or `MessagesState`), you **must explicitly define all custom fields in your state TypedDict**. Any fields that are not declared in the schema definition will be silently ignored and not available in your graph.
When defining all state keys: when extending a state schema (e.g., extending `AgentState` or `MessagesState`), you **must explicitly define all custom fields in your state TypedDict**. Any fields that are not declared in the schema definition will be silently ignored and not available in your graph.

Copilot uses AI. Check for mistakes.
For example:

```python
from langgraph.graph import MessagesState

# ✗ WRONG - custom fields are not defined in the schema
class WrongState(MessagesState):
authenticated: bool # This field will be silently ignored!
user_id: str # This field will be silently ignored!

# ✓ CORRECT - use TypedDict to properly extend the schema
from typing_extensions import TypedDict

class CorrectState(MessagesState, TypedDict):
authenticated: bool # Properly defined
user_id: str # Properly defined
```

This applies to any custom state you create by extending existing state schemas. Always use `TypedDict` to ensure your custom fields are properly declared and will be persisted in your graph state.

See [#34108](https://github.com/langchain-ai/langgraph/issues/34108) for more context.
Copy link

Copilot AI Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The GitHub issue reference uses the wrong repository. The link references github.com/langchain-ai/langgraph/issues/34108, but according to the PR description, this should reference langchain-ai/langchain#34108. The issue number suggests this is in the langchain repository, not langgraph.

The link should be updated to reference the correct repository or use a full URL format if cross-repository references are needed.

Suggested change
See [#34108](https://github.com/langchain-ai/langgraph/issues/34108) for more context.
See [#34108](https://github.com/langchain-ai/langchain/issues/34108) for more context.

Copilot uses AI. Check for mistakes.
:::
Comment on lines +87 to +113
Copy link

Copilot AI Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This warning callout is only wrapped in Python-specific language fences (:::python would be needed), but it's placed outside of any language-specific block. Since this warning discusses Python-specific concepts (TypedDict, MessagesState), it should either be:

  1. Wrapped in :::python / ::: fences to indicate it's Python-specific, or
  2. Include a JavaScript/TypeScript equivalent example if this issue also applies to JavaScript/TypeScript users.

Looking at the context, the Schema section has both :::python and :::js blocks (lines 74-84), so this warning should follow the same pattern to maintain consistency with the documentation structure.

Copilot uses AI. Check for mistakes.


#### Multiple schemas

Typically, all graph nodes communicate with a single schema. This means that they will read and write to the same state channels. But, there are cases where we want more control over this:
Expand Down