langchain-ai / langchain-ai/langgraphjs

Feature Request: Support for State Schema Versioning & Migration in LangGraph.js

Open
#536 7 comments 11 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
3.3k
Forks
580
Avg merge
1d 1h
Merged PRs (30d)
56

Description

### Background

Today LangGraph allows me to persist application state via Checkpointers and Stores. Once the application is deployed to real users, you can expect that a history of persisted checkpoints will accumulate. However, LangGraph currently provides no built-in functionality for detecting or managing incompatible changes in the structure of this state over time.

As applications mature, it's common for the structure of the state to evolve. These changes can range from adding new fields, changing field types, or even restructuring objects. These changes may cause older persisted states to become incompatible with newer versions of the application, leading to failures when resuming workflows from checkpoints.

It's also common for users to store objects in their application state that aren't defined by their application. As one trivial example, most applications have a `messages` channel in their state that is of type `BaseMessage[]`. Over time application maintainers will need to update their dependencies, which may in turn modify the structure of their persisted state. Ideally this will happen in a controlled manor, but occasionally these updates will need to be done with urgency, for example due to newly discovered security vulnerabilities in the dependencies that define these portions of the application state.

### Problem Statement

There are two primary challenges that applications face when managing changes to persisted state:

1. **Identifying Incompatibility**: Detecting when a persisted state no longer matches the structure expected by the running application. For example, if a new required field is added to the `messages` state, older checkpoints will lack this field, leading to runtime errors.

2. **Migrating Incompatible States**: Providing a mechanism to transform these incompatible states into a structure that is compatible with the current application schema. This transformation might need to occur lazily, at the time the state is loaded, or proactively, when the schema changes.

These concerns are relevant not only for future versions of an application but also for cases where an application rollback occurs, which could introduce older versions of code interacting with newer states.

### Proposed Solution

I believe there are lightweight ways LangGraph.js could address this:

- **Version-Tagged States**: LangGraph.js could allow developers to tag either channels or state objects with a version identifier at the time of persistence. When the state is retrieved, LangGraph could expose lifecycle hooks or interceptors, allowing developers to implement custom migration logic before the state is used in the application.

- **Lazy Online Migration**: By using these version tags, LangGraph could support a "roll-forward-only" migration model, where older states are updated to the latest version when accessed. This could be optional, allowing applications that don't need it to ignore the feature.

- **Schema Change Detection**: Expose a mechanism that warns or throws an error when a checkpoint’s state doesn’t match the expected structure. This would give developers an opportunity to trigger appropriate migration logic.

While it's understandable that LangGraph.js might not want to impose prescriptive migration strategies (given the flexibility of its checkpointer system), these small, optional enhancements could benefit the majority of applications without constraining the flexibility that more advanced users might need.

### Why This Matters

As applications scale and evolve, breaking changes to application state structures become inevitable. Without explicit support for detecting and handling these changes, developers must implement their own ad-hoc solutions, which can introduce bugs and operational complexity. Many other systems that persist application state—such as databases and event-sourcing architectures—include tools to help manage schema evolution. I believe adding even minimal support for this in LangGraph.js would greatly improve its suitability for long-lived, production-grade applications.

It's also important to think about the ecosystem that you want to grow up around LangGraph. Treating state schema versioning as a "first class citizen" in the API will mean that third party authors of generic checkpointers and stores will be more likely to provide a consistent level of support for these concerns, as state schema versioning will feel more like a required thing for these components.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing Checkpointer and Store APIs and how persisted application state is loaded and resumed. The issue needs an agreed design for optional version tagging, incompatibility detection, and migration hooks, with completion defined by an implementable API and its behavior for older checkpoints.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend, data
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.