diff --git a/src/oss/langgraph/graph-api.mdx b/src/oss/langgraph/graph-api.mdx
index 821557d44e..573a19d5b4 100644
--- a/src/oss/langgraph/graph-api.mdx
+++ b/src/oss/langgraph/graph-api.mdx
@@ -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.
+
+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.
+:::
+
+
 #### 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: