langchain-ai/docs
1
0
Fork 0
mirror of https://github.com/langchain-ai/docs.git synced 2026-07-22 12:25:55 -04:00
Code Issues 490 Packages Projects Releases Wiki Activity

[GH-ISSUE #1807] [langgraph]: Document @task checkpointing limitation when using LangGraph API server #235

New Issue
Open
opened 2026-02-17 17:19:28 -05:00 by yindo · 0 comments
yindo commented 2026-02-17 17:19:28 -05:00
Owner
Copy Link
Copy Source

Originally created by @sambhavk on GitHub (Dec 9, 2025).
Original GitHub issue: https://github.com/langchain-ai/docs/issues/1807

Type of issue

issue / bug

Language

Python

Description

Documentation URL

What is missing or incorrect?

The documentation does not mention that @task checkpointing does not work when deploying via LangGraph API server (or langgraph dev). This is a critical limitation that causes silent failures in durable execution.

Current documentation states:

Durable Execution page:

"You can use tasks from both the StateGraph (Graph API) and the Functional API."

"If a node contains multiple operations, you may find it easier to convert each operation into a task rather than refactor the operations into individual nodes."

Persistence page:

"When using the LangGraph API, you don't need to implement or configure checkpointers manually - persistence is handled automatically by the platform."

What actually happens:

When using @task inside a StateGraph node with API server deployment:

  1. API server rejects compile-time checkpointers with error: "Your graph includes a custom checkpointer... please remove the custom checkpointer"
  2. API server injects checkpointer at runtime
  3. Node-level state checkpointing works correctly
  4. Task-level result caching does not work - tasks re-execute on resume

This breaks durable execution for the exact use case the docs recommend.

Example of broken behavior:

from langgraph.func import task
from langgraph.types import interrupt
import random

@task
def fetch_live_stats():
    """Non-deterministic - should be cached on resume"""
    return {"player": random.choice(["Messi", "Ronaldo"]), "score": random.randint(1, 5)}

def recommendation_node(state):
    stats = fetch_live_stats().result()  # Executes at T1
    recommended = stats["player"]
    
    user_choice = interrupt(f"Recommend: {recommended}. Confirm?")  # Pause here
    
    # ON RESUME: fetch_live_stats() executes AGAIN at T2
    # May return different player, breaking consistency
    
    return {"recommendation": recommended, "confirmed": user_choice}

Root cause:

Task checkpointing requires Pregel.checkpointer to be set at compile time. The schedule_task function in langgraph/pregel/_runner.py loads cached task results from Pregel.checkpointer. When compiled without a checkpointer (as required by API server), this is None, so task results cannot be loaded on resume.

Suggested documentation update

Add a callout/warning to the Durable Execution page:

⚠️ Important: When deploying via LangGraph API server or langgraph dev, @task checkpointing inside StateGraph nodes is not supported. The API server injects checkpointers at runtime, but task-level caching requires a compile-time checkpointer.

Workarounds:

  1. Use separate nodes instead of @task for non-deterministic operations
  2. Use the pure Functional API (@entrypoint + @task) where @entrypoint accepts a compile-time checkpointer
  3. Ensure code before interrupt() is idempotent

Node-level state checkpointing works correctly with API server - only task-level granularity is affected.

Also update the Persistence page to clarify:

"Automatic persistence handles node-level state checkpointing. For task-level durable execution, see [limitations with @task]."

Related issues

  • Bug report: #6559 - @task checkpointing does not work with API server runtime-injected checkpointer
  • Related: #5790 - langgraph dev ignores checkpointer configuration

Additional context

  • This limitation was discovered through source code analysis of langgraph/func/__init__.py and langgraph/pregel/_runner.py
  • Affects users building HITL workflows with non-deterministic operations before interrupt points
  • The bug report (#6559) contains detailed technical root cause analysis
Originally created by @sambhavk on GitHub (Dec 9, 2025). Original GitHub issue: https://github.com/langchain-ai/docs/issues/1807 ### Type of issue issue / bug ### Language Python ### Description ## Documentation URL - https://langchain-ai.github.io/langgraph/concepts/durable_execution/ - https://langchain-ai.github.io/langgraph/concepts/persistence/ ## What is missing or incorrect? The documentation does not mention that `@task` checkpointing **does not work** when deploying via LangGraph API server (or `langgraph dev`). This is a critical limitation that causes silent failures in durable execution. ### Current documentation states: **Durable Execution page:** > "You can use tasks from both the StateGraph (Graph API) and the Functional API." > "If a node contains multiple operations, you may find it easier to convert each operation into a task rather than refactor the operations into individual nodes." **Persistence page:** > "When using the LangGraph API, you don't need to implement or configure checkpointers manually - persistence is handled automatically by the platform." ### What actually happens: When using `@task` inside a StateGraph node with API server deployment: 1. API server rejects compile-time checkpointers with error: *"Your graph includes a custom checkpointer... please remove the custom checkpointer"* 2. API server injects checkpointer at runtime 3. **Node-level** state checkpointing works correctly 4. **Task-level** result caching **does not work** - tasks re-execute on resume This breaks durable execution for the exact use case the docs recommend. ### Example of broken behavior: ```python from langgraph.func import task from langgraph.types import interrupt import random @task def fetch_live_stats(): """Non-deterministic - should be cached on resume""" return {"player": random.choice(["Messi", "Ronaldo"]), "score": random.randint(1, 5)} def recommendation_node(state): stats = fetch_live_stats().result() # Executes at T1 recommended = stats["player"] user_choice = interrupt(f"Recommend: {recommended}. Confirm?") # Pause here # ON RESUME: fetch_live_stats() executes AGAIN at T2 # May return different player, breaking consistency return {"recommendation": recommended, "confirmed": user_choice} ``` ### Root cause: Task checkpointing requires `Pregel.checkpointer` to be set at **compile time**. The `schedule_task` function in `langgraph/pregel/_runner.py` loads cached task results from `Pregel.checkpointer`. When compiled without a checkpointer (as required by API server), this is `None`, so task results cannot be loaded on resume. ## Suggested documentation update Add a callout/warning to the Durable Execution page: > **⚠️ Important:** When deploying via LangGraph API server or `langgraph dev`, `@task` checkpointing inside StateGraph nodes is **not supported**. The API server injects checkpointers at runtime, but task-level caching requires a compile-time checkpointer. > > **Workarounds:** > 1. Use separate nodes instead of `@task` for non-deterministic operations > 2. Use the pure Functional API (`@entrypoint` + `@task`) where `@entrypoint` accepts a compile-time checkpointer > 3. Ensure code before `interrupt()` is idempotent > > Node-level state checkpointing works correctly with API server - only task-level granularity is affected. Also update the Persistence page to clarify: > "Automatic persistence handles **node-level** state checkpointing. For **task-level** durable execution, see [limitations with @task]." ## Related issues - **Bug report:** #6559 - @task checkpointing does not work with API server runtime-injected checkpointer - **Related:** #5790 - langgraph dev ignores checkpointer configuration ## Additional context - This limitation was discovered through source code analysis of `langgraph/func/__init__.py` and `langgraph/pregel/_runner.py` - Affects users building HITL workflows with non-deterministic operations before interrupt points - The bug report (#6559) contains detailed technical root cause analysis
yindo added the langgraphexternal labels 2026-02-17 17:19:28 -05:00
yindo changed title from [langgraph]: Document @task checkpointing limitation when using LangGraph API server to [GH-ISSUE #1807] [langgraph]: Document @task checkpointing limitation when using LangGraph API server 2026-06-05 17:25:48 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
deepagents
docs-infra
external
external
help wanted
integration
internal
internal
javascript
js/ts
langchain
langgraph
langsmith
needs-title
pull-request
Mirrored from GitHub Pull Request
 python
reference
No Label external langgraph
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/docs#235
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?