[langgraph]: Document @task checkpointing limitation when using LangGraph API server

[sambhavk]

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:

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