Heuristic:Langchain ai Langgraph Deprecation Migration Guide
| Knowledge Sources | |
|---|---|
| Domains | Migration, API_Stability, Best_Practices |
| Last Updated | 2026-02-11 14:00 GMT |
Overview
Guide for handling LangGraph deprecation warnings and migrating from deprecated APIs to their replacements before removal in v2.0.
Description
LangGraph uses a versioned deprecation warning system inspired by Pydantic. Deprecated features emit `LangGraphDeprecationWarning` subclasses that include the version where deprecation was introduced and the expected removal version. Currently, two deprecation tiers exist: features deprecated since v0.5 (removal in v2.0) and features deprecated since v1.0 (removal in v2.0). The system uses Python's standard `warnings` module and the `typing_extensions.deprecated` decorator.
Usage
Use this heuristic when upgrading LangGraph versions, when you see `LangGraphDeprecationWarning` in your logs, or when planning a migration to ensure your code remains compatible with future releases.
The Insight (Rule of Thumb)
- `NodeInterrupt` class: Deprecated since v1.0. Replace with `interrupt()` function from `langgraph.types`.
- `ValidationNode` class: Deprecated since v1.0. Replace with `create_agent` from `langchain.agents` with custom tool error handling.
- `checkpoint_during` parameter: Deprecated since v1.0. Replace with the `durability` parameter (`"sync"`, `"async"`, or `"exit"`).
- `AgentState` class: Deprecated. Use `MessagesState` or define your own `TypedDict` with `Annotated[list, add_messages]`.
- `Send`/`Interrupt` imports from `langgraph.constants`: Deprecated since v1.0. Import from `langgraph.types` instead.
- Action: Run your code with `warnings.simplefilter("always", LangGraphDeprecationWarning)` to surface all deprecation warnings during development.
- Trade-off: Migrating early avoids breaking changes when v2.0 is released; ignoring warnings risks hard failures on upgrade.
Reasoning
The versioned deprecation system provides a clear timeline for API changes. Each deprecation warning includes the exact version it was introduced and when it will be removed, allowing teams to plan migrations. The Pydantic-inspired approach (with `since` and `expected_removal` tuples) is familiar to the Python ecosystem and integrates naturally with CI/CD warning filters.
The current deprecation categories indicate that v2.0 will be a significant breaking change, removing features deprecated across both v0.5 and v1.0. Early migration prevents accumulating technical debt.
Code Evidence
Deprecation warning infrastructure from `libs/langgraph/langgraph/warnings.py:12-61`:
class LangGraphDeprecationWarning(DeprecationWarning):
"""A LangGraph specific deprecation warning."""
message: str
since: tuple[int, int]
expected_removal: tuple[int, int]
def __str__(self) -> str:
message = (
f"{self.message}. Deprecated in LangGraph V{self.since[0]}.{self.since[1]}"
f" to be removed in V{self.expected_removal[0]}.{self.expected_removal[1]}."
)
return message
class LangGraphDeprecatedSinceV10(LangGraphDeprecationWarning):
def __init__(self, message: str, *args: object) -> None:
super().__init__(message, *args, since=(1, 0), expected_removal=(2, 0))
NodeInterrupt deprecation from `libs/langgraph/langgraph/errors.py:92-104`:
@deprecated(
"NodeInterrupt is deprecated. Please use `interrupt` instead.",
category=None,
)
class NodeInterrupt(GraphInterrupt):
"""Raised by a node to interrupt execution."""
def __init__(self, value: Any, id: str | None = None) -> None:
warn(
"NodeInterrupt is deprecated. Please use `langgraph.types.interrupt` instead.",
LangGraphDeprecatedSinceV10,
stacklevel=2,
)