The Complete LangGraph Guide

This is part one of three. It covers everything you need to build a real LangGraph application, not a demo you throw away. By the end you can define a graph's state, write nodes, branch between them, give a conversation memory that survives a restart, stream output token by token, pause a run to ask a human for approval, and read the error messages LangGraph produces when you get it wrong. Mid-level and Senior take the same topics further; nothing here is wasted.

Everything below was checked against LangGraph 1.2.12, released 21 September 2026. LangGraph follows semantic versioning, so anything on the 1.2 line behaves the same way. Where the official documentation and the shipped code disagree, this guide says so rather than picking one quietly.

Each section ends with a Try it task. Do them as you go. Graphs are one of those topics that feel abstract on the page and obvious the moment you have watched your own graph loop, pause, and resume.

What LangGraph is, and the problem it solves

LangGraph is a low-level orchestration framework and runtime for building long-running, stateful agents. You describe your application as a graph: a shared piece of data called the state, a set of functions called nodes that each read the state and return an update to it, and edges that decide which node runs next. LangGraph runs that graph, saves the state after every step, and lets you stop, inspect, rewind and resume it.

Notice what is not in that description. LangGraph does not write your prompts, does not pick your model, and does not decide what an agent is. It has no opinion about whether your application is an agent at all. It is the machinery underneath: the part that remembers where you were and decides what happens next. LangChain's create_agent is the higher-level agent framework built on top of it, and LangSmith is the separate product that traces, evaluates and deploys what you build. You can use LangGraph with none of those.

The problem it solves becomes obvious the second time you write an LLM application. The first one is a function: take a question, call a model, return the answer. The second one needs to call a tool, look at the result, maybe call another tool, maybe ask the user a clarifying question, and stop when it is finished. Written by hand, that becomes a while True: loop around a growing list of messages, with a pile of if statements inside it.

That loop works until it meets reality, and then four things go wrong at once.

It forgets everything when the process ends. The conversation lives in a local variable. Restart your server, deploy a new version, or let a request time out, and the user starts over. For a chatbot that is annoying. For a workflow that has already charged a customer's card, it is a bug with a cost attached.

You cannot pause it. Any workflow that needs a human to approve something — a refund, an outbound email, a database migration — has to stop mid-flight, wait an unknown length of time, and then carry on from exactly where it was. A while loop in a request handler cannot wait three hours.

You cannot see inside it. When the loop calls the wrong tool on step seven, you have a list of messages and a guess. There is no record of what the state looked like at step six.

Every retry starts from zero. If the fourth of five model calls fails, you pay for the first three again.

LangGraph's answer is to make the loop a data structure instead of control flow. Because the graph is described rather than executed inline, the runtime can checkpoint it, pause it, replay it, visualise it, and stream from it.

The lineage is worth knowing, because it explains the vocabulary. LangGraph's execution model comes from Pregel, Google's system for large-scale graph processing, and from Apache Beam. That is where the word "super-step" comes from, and it is why nodes communicate by writing to shared channels rather than by calling each other. The public API deliberately resembles NetworkX: you add nodes, you add edges, you compile.

Graphs versus the loop you would have written

Before committing to the graph model, it is worth being honest about what you give up, because LangGraph is not free. A graph is more code than a loop for a small task, and the indirection is real: you cannot read a graph top to bottom the way you read a function.

The honest rule for choosing: if your application is one model call with no branching and no memory, write the function. The moment it has a loop, needs to remember a conversation, or has to survive a restart, the graph pays for itself. Most teams arrive at LangGraph from the second direction, having already written the loop and discovered its limits.

There is a second axis you will meet in the documentation and should know exists even though this guide does not teach it. LangGraph offers two front ends over the same runtime. The Graph API is what you are about to learn: StateGraph, nodes and edges, written out explicitly. The Functional API uses @entrypoint and @task decorators with ordinary Python control flow — if, for, while — and gets you checkpointing and interrupts without drawing a graph. It compiles down to a single node, which has a consequence you need to know before you reach for it: on resume it replays your function from the beginning, using cached results for tasks that already completed. Anything outside a task must therefore be deterministic. Start with the Graph API. It makes the execution model visible, and the visible version is the one you can debug.

The four nouns: state, node, edge, super-step

Almost everything in LangGraph is built from four ideas. Learn them precisely now and the rest of the API will look like consequences rather than new material.

State is the shared data structure that is passed between nodes. You declare its shape with a schema, and the most common choice is a TypedDict: a dictionary whose keys and value types are written down. You can also use a dataclass, which gives you default values, or a Pydantic BaseModel, which validates values at runtime at some cost in speed. The state is not a bag of globals — it is the single place your graph keeps what it knows.

A node is a Python function, synchronous or asynchronous, that takes the state and returns a partial update: a dictionary containing only the keys it wants to change. This is the single most important detail in the whole model. A node does not return the new state. It returns a small dictionary of changes, and LangGraph merges them. A node that only sets a counter returns {"count": 3} and says nothing about the other twelve keys.

An edge says what runs next. A normal edge, add_edge("a", "b"), always goes from a to b. A conditional edge, add_conditional_edges("a", router), calls your router function with the state; the router returns the name of the next node, a list of names, or END. Two virtual nodes mark the boundaries: START is where input enters, and END is where the run finishes. They are not functions you write, just names.

A super-step is one tick of the runtime. Every node triggered in the same tick runs in parallel, and their updates are applied together at the end of the step. One checkpoint is written per super-step. This explains behaviour that is otherwise baffling: if two parallel nodes both write the same state key in one step, LangGraph does not know which should win, and it refuses rather than guessing.

Two more words you will see immediately and should not be scared of. A channel is the low-level storage slot behind one state key; the default channel type simply overwrites, which is why an ordinary key behaves like a variable. A reducer is a function you attach to a key to say how updates combine instead of overwriting. The next-but-one section is entirely about reducers, because they cause most beginner confusion.

It is worth pausing on why the super-step exists at all, because it is the one idea with no equivalent in ordinary Python. In a normal program, a function's effects are visible the instant it returns. In a Pregel-style runtime, effects are collected and applied at a boundary. That buys two things. It makes parallelism safe without locks, because no node ever observes another node's half-finished write. And it gives the runtime a natural place to save: one consistent snapshot per step, rather than a smear of partial updates. Every feature in the rest of this guide — memory, resume, replay, streaming — is built on that boundary existing.

The practical consequence for your code is a small discipline. A node should read the state it was given and return its update. It should not expect to see a sibling node's write within the same step, and it should not reach outside the state to communicate. When you find yourself wanting a node to see something another node just produced, the answer is almost always to put the second node in a later step with an edge, not to work around the boundary.

Finally, compile. You build a graph with StateGraph, then call .compile(). Compiling validates the structure — it catches orphan nodes, missing entry points and edges pointing at names that do not exist — and returns a CompiledStateGraph. That object is a LangChain Runnable, which is where invoke, stream, batch and their async twins come from. You must compile before you can run anything.

Installing LangGraph and checking the setup

LangGraph is a pure-Python package with ordinary dependencies, so installation is unremarkable on Linux, macOS and Windows. The one requirement to note is Python: the library needs Python 3.10 or newer, and the command-line tool's local development server needs 3.11 or newer, because it pulls in the Agent Server package.

Start with a virtual environment. On Linux or macOS:

python3 -m venv .venv
source .venv/bin/activate
pip install -U langgraph

On Windows with PowerShell:

py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1
pip install -U langgraph

If PowerShell refuses to run the activation script, Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once will fix it. If you prefer uv, uv venv && source .venv/bin/activate && uv add langgraph does the same job faster.

That one package is enough to build and run graphs. Models and tools are separate, because LangGraph does not depend on any model provider:

pip install -U langchain            # create_agent, model wrappers, tool helpers
pip install -U langchain-openai     # or langchain-anthropic, etc.

For a conversation that survives a restart you want a real checkpointer. SQLite is the right choice while you are learning, and Postgres is the one you will use at work:

pip install -U langgraph-checkpoint-sqlite
pip install -U "psycopg[binary,pool]" langgraph-checkpoint-postgres

Finally, the CLI and the local development server. The quotes around the extras matter — zsh, which is the default shell on macOS, treats square brackets as a glob pattern and will tell you there is no match:

pip install -U "langgraph-cli[inmem]"

Now verify all of it. Three checks, each of which fails loudly if something is wrong:

python -c "import importlib.metadata as m; print(m.version('langgraph'))"
# 1.2.12

langgraph --help
# usage: langgraph [OPTIONS] COMMAND [ARGS]...

langgraph dev
# starts on http://127.0.0.1:2024, prints a Studio link, serves OpenAPI at /docs
curl http://127.0.0.1:2024/ok
# {"ok":true}

langgraph dev runs the server in process with in-memory storage and does not need Docker. The commands that build container images — langgraph build and langgraph up — do. If langgraph dev opens a browser you cannot use, Safari and locked-down corporate networks are the usual culprits; langgraph dev --tunnel serves it through a public tunnel instead. Its other useful flags are --port (default 2024), --host (default 127.0.0.1), --no-browser and --no-reload.

Your first graph, step by step

We will build the smallest useful graph: one node that produces a message. No model key is needed, because a fake model teaches the mechanics better than a real one — when something goes wrong you know it is your graph and not the network.

from langgraph.graph import StateGraph, MessagesState, START, END


def mock_llm(state: MessagesState):
    return {"messages": [{"role": "ai", "content": "hello world"}]}


builder = StateGraph(MessagesState)
builder.add_node(mock_llm)
builder.add_edge(START, "mock_llm")
builder.add_edge("mock_llm", END)
graph = builder.compile()

result = graph.invoke({"messages": [{"role": "user", "content": "hi!"}]})
for message in result["messages"]:
    message.pretty_print()

Running it prints the user message followed by the AI message. Six lines of graph code, and every one of them is doing something worth naming.

StateGraph(MessagesState) creates a builder whose state schema is MessagesState, a prebuilt schema with a single key, messages, that holds a list of messages and knows how to append to it. You will use it constantly.

builder.add_node(mock_llm) registers the function as a node. Passing the function alone takes the node's name from the function's name — hence "mock_llm" in the edges below. You can be explicit instead: builder.add_node("call_model", mock_llm). Be deliberate, because the name is what edges, streamed updates, checkpoints and traces all refer to.

The two add_edge calls connect the virtual START node to your node and your node to END. Without the first one, compiling fails: a graph with no path from START has no way to begin.

builder.compile() validates and returns the runnable graph. graph.invoke(...) runs it to completion and returns the final state.

Look closely at what the node returned: {"messages": [...]}, a list with one new message — not the whole conversation. The user's message is still in the result because MessagesState's messages key appends rather than overwrites. That append is a reducer, and the next section is about what happens when you forget to ask for one.

Now make it a graph with more than one step, and with state of your own design:

from typing import TypedDict
from langgraph.graph import StateGraph, START, END


class State(TypedDict):
    topic: str
    draft: str
    word_count: int


def write_draft(state: State) -> dict:
    return {"draft": f"A short note about {state['topic']}."}


def count_words(state: State) -> dict:
    return {"word_count": len(state["draft"].split())}


builder = StateGraph(State)
builder.add_node("write_draft", write_draft)
builder.add_node("count_words", count_words)
builder.add_edge(START, "write_draft")
builder.add_edge("write_draft", "count_words")
builder.add_edge("count_words", END)
graph = builder.compile()

print(graph.invoke({"topic": "checkpointers"}))
# {'topic': 'checkpointers', 'draft': 'A short note about checkpointers.', 'word_count': 5}

Two super-steps, two checkpoints' worth of history if a checkpointer were attached, and a final state containing everything. Note that count_words reads state["draft"], a key it never wrote. That is the whole point of shared state: nodes communicate through it rather than by calling each other.

One habit to adopt immediately: have the graph draw itself.

print(graph.get_graph().draw_mermaid())

That prints Mermaid source you can paste into any Markdown viewer that renders it. draw_mermaid_png() gives you an image instead. For a graph with branches, looking at the picture catches wiring mistakes in seconds that reading code does not.

Reducers, and why your list keeps being overwritten

Here is the bug every beginner writes. A graph collects findings from several nodes, and only the last one survives.

class State(TypedDict):
    findings: list[str]        # no reducer: this key is OVERWRITTEN


def search_docs(state: State) -> dict:
    return {"findings": ["found in the docs"]}


def search_code(state: State) -> dict:
    return {"findings": ["found in the code"]}

Run these one after the other and findings ends up as a single-item list, because the default channel behind a state key simply stores the last value written. Run them in parallel in the same super-step and you get something more useful: an error.

langgraph.errors.InvalidUpdateError: At key 'findings': Can receive only one value per step.
Use an Annotated key to handle multiple values.
For troubleshooting, visit: https://docs.langchain.com/oss/python/langgraph/errors/INVALID_CONCURRENT_GRAPH_UPDATE

That message is telling you exactly what to do. A reducer is a function (current, update) -> new that you attach to a key with Annotated, and it tells LangGraph how to combine writes instead of replacing them:

import operator
from typing import Annotated, TypedDict


class State(TypedDict):
    findings: Annotated[list[str], operator.add]

operator.add on two lists concatenates them, so now both nodes' findings are kept, in parallel or in sequence. The reducer runs at the super-step boundary, where all the step's writes are applied together.

For messages there is a purpose-built reducer, add_messages, and MessagesState is simply a state that uses it:

from typing import Annotated, TypedDict
from langchain_core.messages import AnyMessage
from langgraph.graph.message import add_messages


class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]

add_messages does three things that plain concatenation cannot. It appends new messages. It replaces by message ID, so re-emitting a message with the same ID edits it rather than duplicating it. And it accepts plain dictionaries such as {"role": "user", "content": "hi"} as well as message objects, converting them for you. That last point is why the first example in this guide could pass a dictionary.

Now the trap that follows from all of this, and it catches experienced people too.

from langgraph.types import Overwrite

def reset(state: State) -> dict:
    return {"findings": Overwrite([])}

Read it as a rule you can apply without thinking: a key with no reducer behaves like a variable, a key with a reducer behaves like an accumulator, and Overwrite is how you assign to an accumulator.

Branching: conditional edges and loops

Straight lines are rarely what you want. A conditional edge gives the graph a decision: a function that reads the state and returns where to go next.

from typing import Annotated, TypedDict
import operator
from langgraph.graph import StateGraph, START, END


class State(TypedDict):
    question: str
    attempts: Annotated[int, operator.add]
    answer: str


def attempt(state: State) -> dict:
    return {"attempts": 1, "answer": "not sure yet"}


def finalise(state: State) -> dict:
    return {"answer": f"answered after {state['attempts']} attempts"}


def route(state: State) -> str:
    if state["attempts"] >= 3:
        return "finalise"
    return "attempt"


builder = StateGraph(State)
builder.add_node("attempt", attempt)
builder.add_node("finalise", finalise)
builder.add_edge(START, "attempt")
builder.add_conditional_edges("attempt", route, ["attempt", "finalise"])
builder.add_edge("finalise", END)
graph = builder.compile()

print(graph.invoke({"question": "why?", "attempts": 0, "answer": ""}, {"recursion_limit": 10}))
# {'question': 'why?', 'attempts': 3, 'answer': 'answered after 3 attempts'}

Three details carry the weight here.

The router is a plain function. It receives the state and returns a node name, a list of node names, or END. It must not return anything else; a typo in the returned string becomes a runtime error rather than a wrong branch.

The third argument to add_conditional_edges lists the possible destinations. You can pass a list of node names, or a dictionary mapping the router's return values to node names when the two differ. It is optional for execution but not for drawing: without it, the rendered diagram cannot show where the branch can go.

The graph loops. attempt routes back to attempt, which is perfectly legal and is how every agent works. The exit condition lives in the router, and if you get it wrong the graph runs until the recursion limit stops it.

There is a second way to route, and you should recognise it even though you will not need it on day one. Returning a Command object from a node combines the state update and the routing decision in one place:

from typing import Literal
from langgraph.types import Command


def attempt(state: State) -> Command[Literal["attempt", "finalise"]]:
    if state["attempts"] >= 2:
        return Command(update={"attempts": 1}, goto="finalise")
    return Command(update={"attempts": 1}, goto="attempt")

Use conditional edges when the decision is about the graph's shape and belongs outside the node. Use Command when the node itself has just learned something that decides where to go, typically because a model told it. Both are first-class; neither is deprecated.

Memory: checkpointers and threads

So far every invoke has started from nothing. To give a graph memory you attach a checkpointer at compile time and pass a thread ID at call time. Those two things together are LangGraph's entire short-term memory story.

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, MessagesState, START, END


def echo(state: MessagesState) -> dict:
    last = state["messages"][-1].content
    return {"messages": [{"role": "ai", "content": f"you said: {last}"}]}


builder = StateGraph(MessagesState)
builder.add_node(echo)
builder.add_edge(START, "echo")
builder.add_edge("echo", END)
graph = builder.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "conversation-1"}}
graph.invoke({"messages": [{"role": "user", "content": "first"}]}, config)
result = graph.invoke({"messages": [{"role": "user", "content": "second"}]}, config)
print(len(result["messages"]))
# 4

Four messages, not two. The second invoke loaded the saved state for conversation-1, appended to it, and saved it again. Change the thread ID and you get a fresh conversation with no shared history. That is how one deployed graph serves thousands of independent users: one thread each.

A checkpoint is a snapshot of the state at the end of a super-step. A thread is the ordered sequence of checkpoints under one thread_id. The checkpointer is the thing that stores them.

Forget the thread ID and the error is specific:

ValueError: Checkpointer requires one or more of the following 'configurable' keys:
thread_id, checkpoint_ns, checkpoint_id

InMemorySaver (also exported as MemorySaver) keeps everything in RAM, which makes it perfect for tests and useless for anything else — restart the process and every conversation is gone. For local work that should survive, use SQLite. For production, use Postgres:

from langgraph.checkpoint.postgres import PostgresSaver

DB_URI = "postgresql://user:pass@localhost:5432/langgraph"
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
    checkpointer.setup()                      # required the first time: creates the tables
    graph = builder.compile(checkpointer=checkpointer)
    graph.invoke({"messages": [...]}, config)

setup() is the step people forget, and forgetting it produces missing-table errors from Postgres rather than a helpful LangGraph message. Call it once, on first use, for the checkpointer and for the store. If you are writing async code, use AsyncPostgresSaver with ainvoke and astream; mixing a synchronous saver into an async graph is a reliable way to confuse yourself.

Because every step is saved, you can look at it:

snapshot = graph.get_state(config)
print(snapshot.values)        # the state right now
print(snapshot.next)          # which nodes run next; () means finished

for past in graph.get_state_history(config):
    print(past.metadata["step"], past.values)   # newest first

A StateSnapshot carries the values, what runs next, the config that identifies it (thread, namespace, checkpoint ID), metadata including the step number and the writes that produced it, and the pending tasks. This is the thing that replaces print-statement debugging. When an agent misbehaved on step seven, you can read step six.

One knob you should know the name of without tuning it yet. Durability controls when checkpoints are actually written: "exit" saves only when the run finishes and is fastest, "async" writes while the next step runs and is the default, and "sync" writes before the next step starts and is safest. Pass it per call as graph.invoke(x, config, durability="sync"). If you see checkpoint_during=True in an older example, that parameter is deprecated and durability replaced it; passing both raises an error.

Streaming: watching the graph work

invoke waits for the whole graph and hands back the final state. That is fine for a batch job and unacceptable for a user interface, where a blank screen for twenty seconds reads as a broken application. stream yields as the graph runs, and stream_mode chooses what you get.

for chunk in graph.stream({"messages": [{"role": "user", "content": "hi"}]}, config, stream_mode="updates"):
    print(chunk)
# {'echo': {'messages': [AIMessage(content='you said: hi')]}}

The modes worth knowing on day one:

There are also "checkpoints" and "tasks" for inspecting persistence and scheduling. You can pass a list — stream_mode=["values", "messages"] — and each yielded item then tells you which mode it came from.

The "custom" mode is the one beginners underuse. A node that spends thirty seconds in a non-LLM operation can report progress itself:

from langgraph.config import get_stream_writer


def index_documents(state: State) -> dict:
    writer = get_stream_writer()
    for i, doc in enumerate(state["docs"]):
        writer({"indexed": i + 1, "total": len(state["docs"])})
    return {"indexed": len(state["docs"])}

A question that comes up immediately: which mode should a chat interface use? In practice, two at once. "messages" drives the typing effect, because it yields model tokens as they arrive, and "updates" tells your interface which node is running so you can show something honest like "searching" or "writing the answer". Streaming only "values" to a browser is tempting because it is simple, but you are then sending the entire conversation state on every step, which gets expensive as a thread grows. Stream the smallest thing that answers the question your interface is asking.

Two things about output shapes will save you confusion when reading the documentation. First, invoke and stream take a version argument, and the default is still "v1". Version "v2", added in 1.1, returns a typed GraphOutput object with .value and .interrupts instead of a plain dictionary. It is opt-in, so everything in this guide uses the v1 shapes. Second, there is a newer, separate method — stream_events(..., version="v3") — with convenient projections such as run.messages and run.values. Current documentation pages often show it and call it recommended, but it is still labelled beta. Learn stream first; it is what the stable API gives you.

Pausing for a human: interrupt

This is the feature that makes LangGraph worth learning even for workflows that barely involve a model. interrupt() stops the graph in the middle of a node, saves the state, and hands a payload back to the caller. Later — seconds or days later — you resume with a value, and that value becomes the return value of the interrupt() call.

from typing import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, interrupt


class State(TypedDict):
    amount: int
    decision: str


def request_approval(state: State) -> dict:
    answer = interrupt({"question": f"Approve a refund of {state['amount']}?"})
    return {"decision": answer}


builder = StateGraph(State)
builder.add_node("request_approval", request_approval)
builder.add_edge(START, "request_approval")
builder.add_edge("request_approval", END)
graph = builder.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "refund-42"}}
first = graph.invoke({"amount": 500, "decision": ""}, config)
print(first["__interrupt__"])
# (Interrupt(value={'question': 'Approve a refund of 500?'}, ...),)

final = graph.invoke(Command(resume="approved"), config)
print(final["decision"])
# approved

The first invoke returns early, with the payload under the __interrupt__ key of the result (that is the v1 output shape; with version="v2" you read result.interrupts instead). The process can now exit entirely. The second invoke passes Command(resume="approved") on the same thread ID, the graph loads its checkpoint, and interrupt() returns "approved".

The rules around interrupt are short, strict, and all follow from one fact: the node re-runs from the beginning on resume. interrupt() works by raising an internal exception, and resuming replays the node with the answer cached.

And the trap that wastes an afternoon: interrupt() needs a checkpointer and a thread ID, but calling it without a checkpointer does not raise an error. The graph returns {'__interrupt__': [...]} exactly as it would otherwise, and there is simply nothing to resume. If a resume appears to do nothing, check that you passed checkpointer= to compile().

New in 1.2.12, you can have the resume value validated instead of trusting whatever arrives, by passing a Pydantic model, TypedDict or dataclass as response_schema:

from pydantic import BaseModel
from langgraph.types import interrupt


class Decision(BaseModel):
    approved: bool
    note: str = ""


def request_approval(state) -> dict:
    decision = interrupt({"question": "Approve?"}, response_schema=Decision)
    return {"decision": "yes" if decision.approved else "no"}

Related but different: interrupt_before=["node"] and interrupt_after=["node"], which you can pass at compile or call time. These are static breakpoints — they pause between nodes rather than inside one, and they exist for debugging and for stepping through a graph in Studio, not for building approval flows.

An agent without writing the loop

Everything so far was hand-built, which is the right way to learn. But the single most common thing people build — a model that can call tools in a loop until it is finished — already exists, and writing it yourself every time is a waste.

from langchain.agents import create_agent


def get_weather(city: str) -> str:
    """Return the weather for a city."""
    return f"It is 34 degrees and sunny in {city}."


agent = create_agent(
    "openai:gpt-4.1",
    tools=[get_weather],
    system_prompt="You are a concise assistant. Use the tools you have.",
)

result = agent.invoke({"messages": [{"role": "user", "content": "weather in Cairo?"}]})
print(result["messages"][-1].content)

create_agent returns a compiled LangGraph graph. Everything you have learned still applies: pass a checkpointer for memory, pass thread_id in the config, stream it, inspect it with get_state. It is not a separate world, it is a graph someone wrote for you.

So when do you build the graph yourself? When you need control the agent loop does not give you: a fixed sequence of steps, a human approval in the middle, a branch that depends on business rules rather than the model's judgement, or a shape you want to be able to draw for a compliance reviewer. A good instinct is to reach for create_agent when the model should decide what happens next, and for StateGraph when you should decide.

Reading LangGraph's error messages

LangGraph's errors are unusually good: most carry an error code and a link to a page about that exact failure. Learning to read them is faster than learning to avoid them. Here are the ones you will actually hit, with the real text.

InvalidUpdateError: At key 'k': Can receive only one value per step. Use an Annotated key to handle multiple values. Two parallel nodes wrote the same key and it has no reducer. Add one, or stop writing the key from two places at once.

GraphRecursionError: Recursion limit of 5 reached without hitting a stop condition. A cycle with no exit, or a genuinely long graph. Fix the router first — most of the time it should have returned END — and only then consider raising recursion_limit.

InvalidUpdateError: Expected dict, got ['whoops'] A node returned something that is not a dictionary of state keys. Usually one branch of an if forgot to return, or returned a bare list. Every code path must return a dict or a Command.

ValueError: Graph must have an entrypoint: add at least one edge from START to another node You forgot add_edge(START, "first"). Compiling catches it, which is exactly why compiling exists.

ValueError: Found edge ending at unknown node 'nope' A typo, or an edge added with a name that does not match the node's registered name. This is the usual punishment for letting add_node(fn) choose names implicitly and then renaming the function.

ValueError: Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_id You compiled with a checkpointer and invoked without a thread ID.

ValueError: Node timeouts are only supported for async nodes because sync Python execution cannot be safely cancelled in-process. Node 'a' is sync. You put a timeout on a def node. Make it async def. Timeouts are a 1.2 feature covered at Senior level, but the message is worth recognising.

Blocking-I/O warnings under langgraph dev. The development server detects synchronous blocking calls inside async code — requests.get, a synchronous database driver — and complains, because one blocked node can stall the whole event loop. The right fix is async clients (httpx.AsyncClient, psycopg in async mode) or asyncio.to_thread. langgraph dev --allow-blocking silences it for local work only.

Deprecation warnings are worth reading rather than filtering. They are specific and they tell you the replacement: "MessageGraph is deprecated in LangGraph v1.0.0, to be removed in v2.0.0. Please use StateGraph with a 'messages' key instead.", "'config_schema' is deprecated and will be removed. Please use 'context_schema' instead.", "'checkpoint_during' is deprecated and will be removed. Please use 'durability' instead." Deprecated features keep working for at least one minor release and are removed only in a major version, so you have time — but a warning you fix today is not a migration you do under pressure later.

A debugging order that works for almost all of these. Read the error code and open the link. Print graph.get_state(config) to see where the graph actually stopped and what next says. Re-run with stream_mode="updates" and watch which node produced the bad value. If the shape of the graph is in doubt, print the Mermaid diagram.

Putting it all together

One small project that uses everything: a support-ticket triage graph that classifies a ticket, drafts a reply, asks a human to approve anything it marks as a refund, and remembers the thread.

from typing import Annotated, TypedDict
import operator

from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, interrupt


class State(TypedDict):
    ticket: str
    category: str
    draft: str
    log: Annotated[list[str], operator.add]
    sent: bool


def classify(state: State) -> dict:
    text = state["ticket"].lower()
    category = "refund" if "refund" in text or "money back" in text else "general"
    return {"category": category, "log": [f"classified as {category}"]}


def draft_reply(state: State) -> dict:
    draft = f"Thanks for getting in touch about your {state['category']} request."
    return {"draft": draft, "log": ["drafted a reply"]}


def human_approval(state: State) -> dict:
    answer = interrupt({"draft": state["draft"], "category": state["category"]})
    return {"log": [f"human said {answer}"], "sent": answer == "approve"}


def send(state: State) -> dict:
    # In real code this is the side effect, and it lives AFTER any interrupt.
    return {"sent": True, "log": ["sent without approval"]}


def route(state: State) -> str:
    return "human_approval" if state["category"] == "refund" else "send"


builder = StateGraph(State)
builder.add_node("classify", classify)
builder.add_node("draft_reply", draft_reply)
builder.add_node("human_approval", human_approval)
builder.add_node("send", send)

builder.add_edge(START, "classify")
builder.add_edge("classify", "draft_reply")
builder.add_conditional_edges("draft_reply", route, ["human_approval", "send"])
builder.add_edge("human_approval", END)
builder.add_edge("send", END)

with SqliteSaver.from_conn_string("triage.db") as checkpointer:
    graph = builder.compile(checkpointer=checkpointer)
    config = {"configurable": {"thread_id": "ticket-1001"}}

    first = graph.invoke(
        {"ticket": "I want a refund for order 55", "category": "", "draft": "", "log": [], "sent": False},
        config,
        {"recursion_limit": 25},
    )
    print(first["__interrupt__"][0].value)
    # {'draft': 'Thanks for getting in touch about your refund request.', 'category': 'refund'}

    final = graph.invoke(Command(resume="approve"), config)
    print(final["sent"], final["log"])
    # True ['classified as refund', 'drafted a reply', 'human said approve']

Read the file against the sections above and nothing in it should be new. State is a TypedDict with one accumulating key, log, which has a reducer because several nodes append to it. Four nodes, each returning a partial update. One conditional edge with its destinations declared so the diagram is accurate. A SQLite checkpointer, so closing the program and reopening it on thread ticket-1001 picks the ticket up where it stopped. One interrupt with its side effect placed after it rather than before. An explicit recursion_limit.

Two things to try with it that turn it from an example into understanding. First, run only the first half, kill the process, start a fresh one, and resume with Command(resume="approve") — the ticket is still waiting in triage.db. Second, print graph.get_state_history(config) and read the thread backwards: every step, with the state as it was and the writes that produced it.

Then take it further in two directions. Replace classify with a real model call and the hard-coded keyword check disappears. Deploy it: write a langgraph.json listing your graph, and langgraph dev serves it with an API and Studio attached.

{
  "dependencies": ["."],
  "graphs": { "triage": "./triage.py:graph" },
  "env": ".env"
}

What you can now do, and what comes next

You can define a state schema and know why a node returns a partial update rather than the whole thing. You can write nodes, wire normal and conditional edges, build a loop and stop it deliberately. You know what a reducer is, why a parallel write without one fails, and why returning [] does not clear an accumulating list. You can attach a checkpointer, give a run a thread ID, inspect any past checkpoint, and resume a graph in a new process. You can stream updates, values and tokens. You can pause for a human and resume safely, and you know the four rules that keep that safe. You can use create_agent when the loop is the standard one, and you can read LangGraph's errors as instructions.

That is genuinely enough to ship something small and useful. The gaps are real, though, and worth naming so you know what you do not yet know.

Persistence and memory in depth. The store for cross-thread memory, semantic search over it, checkpoint TTLs, and what durability mode to choose for a given workload.

Subgraphs. A compiled graph used as a node, which is how a system grows past a dozen nodes without becoming unreadable — along with the three persistence modes a subgraph can have and the MULTIPLE_SUBGRAPHS error.

Map-reduce with Send. Dynamic fan-out from a conditional edge, where you do not know until runtime how many parallel branches there are.

Reliability. RetryPolicy and which exceptions it retries by default, caching with CachePolicy, per-node timeouts, node-level error handlers, and graceful shutdown with RunControl — most of which arrived in 1.2.

Time travel. Replaying from a past checkpoint, and forking a thread with update_state to explore an alternative.

Context and runtime. Passing dependencies with context_schema and reading them through Runtime instead of smuggling them through config.

Deployment. The Agent Server, assistants, crons, double-texting strategies, authentication, and what a real LangSmith Deployment looks like on Postgres and Redis.

Mid-level covers those, plus testing graphs properly and debugging beyond print statements. Senior covers architecture, scaling, multi-tenancy, encryption at rest, migrations against in-flight threads, and when to pick something else entirely.

Two practical next steps while this is fresh. First, instrument what you built: set LANGSMITH_TRACING=true and LANGSMITH_API_KEY, run the triage graph, and look at the trace. Seeing a run as a tree makes the super-step model click in a way that reading about it does not. If you prefer open-source tracing, the Langfuse guide covers the same job with a self-hostable backend, which matters when data residency rules keep traces inside the Gulf or Egypt. Second, when your graph starts retrieving documents, you will want to know whether the answers are any good — that is what the RAGAS guide is for. If you want the higher-level agent framework rather than the runtime, read the LangChain guide next.

One last habit. Pin your versions. langgraph and its checkpointer packages should move together, minor releases land every one to two months and patches often weekly, and a breaking change only arrives in a major version. A lock file is the difference between upgrading when you choose to and upgrading when something breaks.

Sources

• LangGraph overview
• Install LangGraph
• Quickstart
• Graph API
• Use the Graph API
• Choosing between the Graph and Functional APIs
• Pregel runtime
• Persistence
• Checkpointers
• Add memory
• Streaming
• Interrupts and human-in-the-loop
• Durable execution
• Run a local server
• Application structure
• Common errors
• GRAPH_RECURSION_LIMIT
• INVALID_CONCURRENT_GRAPH_UPDATE
• MISSING_CHECKPOINTER
• LangGraph v1 release notes
• Release policy and versioning
• LangSmith CLI reference

Interviewers rarely ask beginners to recite the API. They ask what the tool is for, whether you understand its model, and whether you have actually run it. This file gives you the answers in the order they get asked, the vocabulary that makes an answer sound like experience, and a self-test at the end.

Everything here matches LangGraph 1.2.12 (released 21 September 2026).

The thirty-second answer

LangGraph is a low-level orchestration framework and runtime for building stateful, long-running agents. You describe your application as a graph — a shared state, nodes that return partial updates to it, and edges that decide what runs next — and the runtime checkpoints that state after every step, so the application can be paused for a human, resumed in a different process, inspected, and replayed.

If they want one sentence more, add the boundary: "It deliberately does not abstract prompts or decide what an agent is. LangChain's create_agent is the higher-level agent framework built on top of it, and LangSmith is the separate product for tracing, evaluation and deployment."

The thing to avoid is calling LangGraph "an agent framework". It is the layer underneath one. Saying so correctly is a small signal that you have read the documentation rather than a blog post.

The model, in four nouns

Say these in this order and you will have described the whole thing.

State. The shared data structure passed between nodes, declared with a schema — usually a TypedDict, sometimes a dataclass for defaults or a Pydantic model for runtime validation.

Node. A Python function, sync or async, that takes the state and returns a partial update: a dictionary of only the keys it changes. Not the whole state. If you get one thing right in an interview, get this one right.

Edge. What runs next. add_edge("a", "b") is unconditional; add_conditional_edges("a", router) calls a function that returns a node name, a list of names, or END. START and END are virtual nodes.

Super-step. One tick of the runtime. Nodes triggered in the same tick run in parallel and their writes are applied together at the step boundary, through reducers. One checkpoint is written per super-step.

Then the two supporting words. A reducer is a function (current, update) -> new attached to a state key with Annotated, which says how writes combine instead of overwriting. A checkpointer saves a snapshot of the state at each super-step, keyed by a thread ID, and that is what gives you memory, human-in-the-loop, resume and time travel.

A good closing line for this answer: "LangGraph's execution model comes from Pregel, which is why nodes communicate through shared state rather than by calling each other, and why writes land at a step boundary."

The commands and calls to have ready

You will not be asked to write much, but hesitating over the basics reads badly. Be able to produce this from memory:

from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command, interrupt

builder = StateGraph(MessagesState)
builder.add_node("call_model", call_model)
builder.add_edge(START, "call_model")
builder.add_edge("call_model", END)
graph = builder.compile(checkpointer=InMemorySaver())

config = {"configurable": {"thread_id": "abc"}}
graph.invoke({"messages": [{"role": "user", "content": "hi"}]}, config)

And know what each of these is for:

Two CLI commands are enough at this level: langgraph new scaffolds a project from a template, and langgraph dev runs a local server on http://127.0.0.1:2024 with Studio and an OpenAPI page at /docs. langgraph dev does not need Docker; langgraph build and langgraph up do.

And the minimal config file, because being asked "how is a graph deployed?" usually starts here:

{
  "dependencies": ["."],
  "graphs": { "agent": "./my_agent/agent.py:graph" },
  "env": ".env"
}

Stream modes, briefly

Expect "how would you show progress to a user?" The answer is stream, and which mode depends on what you are showing: "values" gives the full state after each step, "updates" gives only what each node returned keyed by node name, "messages" gives LLM tokens as (chunk, metadata) pairs for a typing effect, and "custom" gives whatever you write with get_stream_writer(). There are also "checkpoints", "tasks" and "debug". You can pass a list of modes.

A detail that marks you out: the default output version is still "v1", so invoke returns a plain dictionary and a pause appears under the __interrupt__ key. Version "v2" is opt-in and returns a typed GraphOutput with .value and .interrupts. There is also a newer stream_events(..., version="v3") method with built-in projections, but it is still labelled beta even though current docs pages show it.

The classic traps, and why they happen

These are the questions that separate "read a tutorial" from "built something".

"Why did my parallel nodes crash with InvalidUpdateError?" Two nodes wrote the same state key in one super-step and that key has no reducer, so the runtime has no rule for combining the writes and refuses to guess. The error says so: "At key 'k': Can receive only one value per step. Use an Annotated key to handle multiple values." Fix: Annotated[list, operator.add] or a custom reducer.

"Why didn't returning [] clear my list?" Because the reducer still runs, and merging an empty list changes nothing. To replace rather than merge, return Overwrite([]) from langgraph.types. This one is a genuinely good interview question and almost nobody gets it first time.

"Why does my code before interrupt() run twice?" Because the node re-executes from the start on resume, with the interrupt's answer cached. Side effects before an interrupt() must be idempotent or moved after it. This is the trap with real consequences — it is how a refund gets issued twice.

"Why did my resume do nothing?" Almost always no checkpointer. And the sharp edge: calling interrupt() without a checkpointer does not raise. You still get {'__interrupt__': [...]} back, but there is nothing saved to resume. The related error you do get, if you compiled with a checkpointer and forgot the thread, is "Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_id."

"Why did my loop run forever?" A router that never returns END. The defaults in 1.x are high — the docs say 1000 super-steps since 1.0.6, and the shipped 1.2.12 code uses 10007, overridable with LANGGRAPH_DEFAULT_RECURSION_LIMIT — so a runaway loop burns a lot of tokens before GraphRecursionError stops it. Always pass {"recursion_limit": N} on a cyclic graph. If you remember 25, that was the pre-1.0.6 default.

"Why did compile fail?" Either no entry point ("Graph must have an entrypoint: add at least one edge from START to another node") or an edge pointing at a name that does not exist ("Found edge ending at unknown node 'nope'"). The second one usually follows from letting add_node(fn) take the name from the function and then renaming the function.

"Why is InvalidUpdateError: Expected dict, got [...] happening?" A node returned something that is not a dict of state keys. Usually one if branch forgot to return.

"Why did it lose everything on restart?" InMemorySaver is RAM only. Use SQLite locally, Postgres in production — and call setup() on the first use of a Postgres saver or store, or you get missing-table errors.

"Why is langgraph dev complaining about blocking calls?" Synchronous I/O inside async code stalls the event loop. Use async clients or asyncio.to_thread; --allow-blocking is a local-development escape hatch, not a fix.

Common interview questions, with model answers

"What problem does LangGraph solve that a while loop does not?" A hand-written loop keeps its state in local variables, so it forgets everything when the process ends, cannot pause for a human, cannot be inspected after the fact, and must restart from zero on retry. LangGraph makes the loop a data structure, which lets the runtime checkpoint it after every super-step. From that one property you get memory, resume, human-in-the-loop, time travel and streaming.

"What does a node return?" A partial update: a dictionary containing only the state keys it changes. LangGraph merges it into the state, applying a reducer where one is declared. A node can also return a Command to combine an update with a routing decision.

"What is the difference between a checkpointer and a store?" A checkpointer saves the state of one thread at each super-step; that is short-term memory, and it is what makes resume and time travel work. A store is cross-thread, long-term key-value memory organised by namespace tuples, for things like a user's preferences that should outlive any single conversation.

"When would you use create_agent instead of building a graph?" When the model should decide what happens next and the standard tool-calling loop is what you want. I build a StateGraph when I need to decide: a fixed sequence, a human approval in the middle, branching on business rules, or a shape I need to be able to draw for a reviewer. create_agent returns a compiled LangGraph graph anyway, so checkpointers, threads and streaming all still apply.

"How do you add human approval to a workflow?" Call interrupt(payload) inside a node. The run stops, the state is checkpointed, and the payload comes back to the caller — under __interrupt__ in the v1 output shape. Later you resume with graph.invoke(Command(resume=value), config) on the same thread_id, and that value becomes the return value of interrupt(). It requires a checkpointer and a thread ID. Because the node replays from its start, I keep side effects after the interrupt, and I never wrap interrupt() in try/except, since it works by raising.

"What is add_messages?" The message reducer. It appends new messages, replaces by message ID so you can edit a message rather than duplicate it, and accepts plain dicts as well as message objects. MessagesState is a prebuilt state that is just messages: Annotated[list[AnyMessage], add_messages].

"What changed in LangGraph 1.0 that I should know about?" It was a stability release: the core graph APIs did not change. The visible changes are that langgraph.prebuilt.create_react_agent was deprecated in favour of langchain.agents.create_agent (and prompt= became system_prompt=), Python 3.9 was dropped, and a set of older pieces were deprecated: MessageGraph, the NodeInterrupt exception, ValidationNode, and the prebuilt agent state classes. Separately, the products were renamed — LangGraph Platform, Server, Cloud and Studio are now LangSmith Deployment, the Agent Server and Studio — while the package names stayed the same.

"Do you need LangChain to use LangGraph?" No. LangGraph has no model provider dependency. You install langchain and a provider package when you want model wrappers, tools and create_agent.

"How would you debug a graph that produced a wrong answer?" Start with graph.get_state(config) to see where it actually stopped and what next says, then walk get_state_history(config) backwards to find the step where the state first went wrong. Re-run with stream_mode="updates" to see which node produced the bad value. If the wiring is in doubt, print get_graph().draw_mermaid(). With tracing on, LangSmith shows the same run as a tree.

"What is durability?" When checkpoints are actually written. "exit" only on run completion, fastest, no mid-run crash recovery. "async" while the next step runs, which is the default. "sync" before the next step starts, the safest. Pass it per call. The older checkpoint_during parameter is deprecated in favour of it.

"Where does LangGraph's execution model come from, and why does it matter?" From Pregel, Google's graph-processing system, and from Apache Beam. It matters because it explains two behaviours that otherwise look arbitrary. Nodes do not call each other; they write to shared state, and those writes are applied together at the end of a super-step. That is what makes parallel nodes safe without locks, since no node ever sees another's half-finished write, and it is what gives the runtime a clean place to checkpoint — one consistent snapshot per step rather than a smear of partial updates.

"What is the difference between a conditional edge and returning a Command?" Both route. A conditional edge puts the decision outside the node, in a router function that reads the state and returns a node name, a list of names, or END; that is the right place when the decision is about the graph's shape. Returning Command(update=..., goto=...) from a node combines a state update with a routing decision in one place, which fits when the node has just learned something — typically from a model — that decides where to go. Neither is deprecated.

"How would you test a graph?" Compile a fresh graph per test with InMemorySaver, so tests do not share state. Test a node on its own with compiled.nodes["name"].invoke(state), which avoids running the whole graph to exercise one function. For a partial run, use update_state(config, values, as_node=...) to put the graph into the state you care about and then invoke from there. Keeping nodes small is what makes any of this pleasant.

"What is the Functional API, and would you use it?" An alternative front end over the same runtime: @entrypoint(checkpointer=...) plus @task, with ordinary Python control flow instead of nodes and edges. You still get checkpointing and interrupts. The catch is that it compiles to a single node and replays your function from the beginning on resume, using cached task results, so anything outside a task must be deterministic and you must not reorder tasks or interrupts before the resume point. I would start with the Graph API because the execution model is visible, which is what makes it debuggable.

Sixty-second self-test

Answer out loud. Any hesitation is a section of the detailed guide to reread.

1. What are the four nouns of LangGraph's model?
2. What exactly does a node return?
3. What two things do you need for memory, and where does each one go — compile time or call time?
4. Two parallel nodes write results. What goes wrong, and what is the fix?
5. How do you clear a key that has a merging reducer?
6. What happens to code above an interrupt() when you resume?
7. How do you resume a paused graph, and what does the resume value become?
8. Name three stream modes and what each one yields.
9. Which output version is the default, and where does a pause appear in it?
10. Why must you never wrap interrupt() in try/except?
11. What is the difference between a thread and a checkpoint?
12. Which import is current: create_react_agent or create_agent, and from where?

Quick answers: state, node, edge, super-step. A partial update, a dict of changed keys only. A checkpointer at compile, a thread_id in the config at call time. InvalidUpdateError because the key has no reducer; add Annotated[list, operator.add]. Overwrite(value) from langgraph.types. It runs again, so it must be idempotent. graph.invoke(Command(resume=value), config) on the same thread; the value becomes the return value of interrupt(). values is the full state per step, updates is per-node returns, messages is LLM tokens. "v1", and the pause is under result["__interrupt__"]. Because interrupt() raises internally and catching it swallows the pause. A thread is the sequence of checkpoints under one thread_id; a checkpoint is one snapshot within it. from langchain.agents import create_agent.

If you want to go further before the interview, the questions get harder in two directions: persistence and reliability — subgraphs, Send fan-out, retries, timeouts, time travel — and deployment, which is the Agent Server with Postgres and Redis behind it. Those are Mid-level and Senior. Being able to say clearly where your knowledge stops is better received than guessing.

The mistakes below are the ones people actually make in their first fortnight with LangGraph, in roughly the order they make them. Each one gets the symptom you will see, the cause underneath it, and the fix. Then the habits worth adopting on day one, and a checklist to run before you call a graph finished.

Checked against LangGraph 1.2.12 (released 21 September 2026).

The mistakes beginners actually make

Returning the whole state from a node

Symptom. Keys mysteriously reset to old values, or an accumulating list grows faster than it should, with duplicates.

Cause. You wrote state["draft"] = x; return state. A node is supposed to return a partial update — only the keys it changed. Returning the whole state means re-writing every key, which for a key with a merging reducer means re-appending everything that was already there.

Fix. Return a small dictionary. return {"draft": x}. Treat the incoming state as read-only; never mutate it in place.

Parallel writes to a key with no reducer

Symptom. InvalidUpdateError: At key 'results': Can receive only one value per step. Use an Annotated key to handle multiple values.

Cause. Two nodes ran in the same super-step and both wrote results. The default channel behind a state key just overwrites, so the runtime has no rule for combining two writes and refuses rather than silently dropping one.

Fix. Give the key a reducer: results: Annotated[list[str], operator.add]. If a list is not what you want, write your own (current, update) -> new function and annotate with that.

Expecting an empty list to clear an accumulator

Symptom. return {"log": []} does nothing at all.

Cause. The reducer still runs, and concatenating an empty list is a no-op.

Fix. Bypass the reducer explicitly.

from langgraph.types import Overwrite

def reset(state: State) -> dict:
    return {"log": Overwrite([])}

Side effects before an interrupt()

Symptom. The email was sent twice. The card was charged twice. The row was inserted twice.

Cause. The node re-executes from its start when you resume. The interrupt's answer is cached, but everything above the interrupt() call runs again.

Fix. Put side effects after the interrupt, or make them idempotent with an operation key. This is the single most expensive beginner mistake in LangGraph, because nothing about it looks wrong in the code.

def refund(state: State) -> dict:
    decision = interrupt({"amount": state["amount"]})   # pause first
    if decision == "approve":
        charge(state["order_id"])                       # side effect after
    return {"refunded": decision == "approve"}

Wrapping interrupt() in try/except

Symptom. The graph never pauses. It runs straight through with an empty or nonsense value.

Cause. interrupt() works by raising an internal exception that the runtime catches. A bare except Exception: anywhere around it swallows the pause.

Fix. Never put interrupt() inside a try block. If you need error handling in that node, do it in a different node.

Interrupt with no checkpointer

Symptom. The first call looks right — you get {'__interrupt__': [...]} back — but resuming does nothing, or starts over.

Cause. There is no checkpointer, so nothing was saved. This does not raise an error, which is why it costs people an afternoon.

Fix. builder.compile(checkpointer=InMemorySaver()), and pass {"configurable": {"thread_id": "..."}} on every call. Treat "interrupt needs a checkpointer and a thread ID" as one indivisible fact.

Missing or reused thread IDs

Symptom. Either ValueError: Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_id, or two users seeing each other's conversation.

Cause. You forgot the config, or you hard-coded "1" while developing and shipped it.

Fix. Derive the thread ID from something real — a conversation ID, a ticket ID, a UUID. Keep it under 255 characters, because longer values cause a database error with the Postgres checkpointer.

Using InMemorySaver as if it were storage

Symptom. Every conversation is gone after a restart or a deploy.

Cause. InMemorySaver (also exported as MemorySaver) is RAM only. It is built for tests.

Fix. langgraph-checkpoint-sqlite for local work that should survive, langgraph-checkpoint-postgres for anything real. And call setup() on first use, or Postgres will complain about missing tables rather than LangGraph telling you what you forgot.

A router that never returns END

Symptom. A long wait, a large model bill, then GraphRecursionError: Recursion limit of N reached without hitting a stop condition.

Cause. A cycle with no exit path, usually because a condition that was supposed to stop the loop is never true.

Fix. Make the exit condition the first thing the router checks, and pass an explicit limit — graph.invoke(x, {"recursion_limit": 25}) — so a bug costs you seconds instead of thousands of calls. The defaults in 1.x are deliberately high: the docs say 1000 super-steps since 1.0.6, while the shipped 1.2.12 code uses 10007 and honours LANGGRAPH_DEFAULT_RECURSION_LIMIT.

A node path that returns nothing

Symptom. InvalidUpdateError: Expected dict, got None or Expected dict, got ['whoops'].

Cause. One branch of an if has no return, or a node returned a bare list or string.

Fix. Every code path returns a dict of state keys, or a Command. If a node has nothing to change, return {} explicitly — it is clearer than falling off the end.

Edge names that do not match node names

Symptom. ValueError: Found edge ending at unknown node 'summarise'.

Cause. You used add_node(fn), which takes the name from the function, and then renamed or moved the function.

Fix. Name nodes explicitly: builder.add_node("summarise", summarise_fn). The name is what edges, streamed updates, checkpoints and traces all refer to, so it deserves to be chosen rather than inherited.

Following tutorials that use deprecated imports

Symptom. Deprecation warnings, or an example that does not match the current documentation.

Cause. Most LangGraph material online predates version 1.0.

Fix. Learn the current spellings once. from langchain.agents import create_agent with system_prompt=, not langgraph.prebuilt.create_react_agent with prompt=. StateGraph with a messages key, not MessageGraph. interrupt(), not the NodeInterrupt exception. from langgraph.types import Send, Interrupt, not langgraph.constants (START and END are fine from either). durability=, not checkpoint_during=. context_schema=, not config_schema=. input_schema=/output_schema=, not input=/output=. retry_policy=, not retry=.

Blocking I/O in an async graph

Symptom. langgraph dev warns about blocking calls; under load, everything is slow at once.

Cause. A synchronous call — requests.get, a blocking database driver, a sleep — inside an async def node. One blocked node stalls the whole event loop.

Fix. Use async clients (httpx.AsyncClient, psycopg in async mode) or wrap the blocking call in asyncio.to_thread. langgraph dev --allow-blocking silences the warning for local experiments; do not treat it as a solution.

Putting secrets in state

Symptom. An API token appears in a trace, or in a checkpoint row in your database.

Cause. State is checkpointed and traced, by design. Anything you put in it is persisted and visible.

Fix. Keep credentials out of state entirely. Read them from the environment inside the node, or pass them as runtime context. This matters more than usual if you are handling personal data under Gulf or Egyptian data-residency rules, where a checkpoint is a stored record and needs to be treated as one.

Mutating the state object in place

Symptom. Changes seem to apply, then vanish, or two parallel nodes interfere in ways that make no sense.

Cause. You did state["messages"].append(msg) instead of returning an update. The state you receive is the runtime's, and reaching into it bypasses the channel and reducer machinery entirely — so the write is neither merged nor checkpointed in the way the rest of the graph assumes.

Fix. Never write to the state you were handed. Build a new value and return it: return {"messages": [msg]}. If you need to transform an existing list, copy it first.

Reading a sibling node's write within the same step

Symptom. A node sees an empty string or a stale value for a key that another node "just set".

Cause. Both nodes were triggered in the same super-step, and writes are only applied at the step boundary. Within a step, every node sees the state as it was at the start.

Fix. Put the reading node in a later step with an edge from the writing node. If you are reaching for a workaround here, the graph shape is telling you something: the dependency is real and should be an edge.

Mixing sync and async carelessly

Symptom. A synchronous checkpointer in an async graph, confusing stack traces, or the state apparently not being saved.

Cause. The checkpointer packages ship both forms — PostgresSaver and AsyncPostgresSaver, SqliteSaver and AsyncSqliteSaver — and the async savers belong with ainvoke/astream.

Fix. Pick one world per application. If your nodes are async def and you call ainvoke, use the Async* saver. Being consistent is worth more than any individual optimisation here.

Guessing at state after an interrupt instead of looking

Symptom. You resume, something is wrong, and you start adding print statements.

Cause. Habit from debugging ordinary code, where there is no record of the past.

Fix. graph.get_state(config) tells you the current values and what next is — an empty tuple means the run finished, anything else means it is waiting. graph.get_state_history(config) gives every past checkpoint, newest first, with the step number and the writes that produced it. Look before you instrument.

Habits worth adopting on day one

Name every node explicitly. One extra string per node, and it immunises you against the whole class of unknown-node errors.

Draw the graph. print(graph.get_graph().draw_mermaid()) after every structural change. Wiring mistakes are instant to see and slow to read.

Set recursion_limit on anything that cycles. Make it part of how you write the invoke call, not something you add after the first runaway.

Compile with a checkpointer from the start. Even for a toy. It costs one argument and it means get_state and get_state_history are available the moment you need to debug something.

Learn get_state_history before you learn to add print statements. It shows the state at every past step with the writes that produced it. It is strictly better information than anything you would print.

Stream while developing. stream_mode="updates" turns a silent twenty-second wait into a visible sequence of nodes. You will spot the wrong branch being taken immediately.

Read error messages to the end. They carry an error code and a link to a page about that exact failure. The link is usually faster than a search.

Pin versions, and pin them together. langgraph and its checkpointer packages should move as a set. Minor releases land every one to two months, patches often weekly, and breaking changes only arrive in a major version — so a lock file means you upgrade when you choose to.

Turn tracing on early. LANGSMITH_TRACING=true plus LANGSMITH_API_KEY, and a run becomes a tree you can read. Seeing one makes the super-step model click properly.

Decide deliberately between create_agent and a hand-built graph. If the model should decide what happens next, use create_agent. If you should decide, build the graph. Both are LangGraph graphs underneath, so nothing is lost either way.

Keep nodes small and boring. A node that does one thing and returns two keys is testable on its own with compiled.nodes["name"].invoke(state). A node that does six things is not.

Write down the state schema before writing any node. The schema is the interface between everything else. Ten minutes on it saves an afternoon of renames.

The checklist

Run this before you call a graph done.

When you are stuck, in order

There is a sequence that resolves most beginner problems faster than reading code, and it is worth following mechanically rather than improvising.

Start with the error message itself, read to the last line. LangGraph attaches an error code and a link to a page about that exact failure, and that page is almost always more specific than anything a search will return.

Then ask the graph where it is. graph.get_state(config) gives you the current values and next; an empty next means the run finished, and a node name in it means the graph is waiting to run that node — which immediately tells you whether you have a routing problem or a node problem.

Then ask when it went wrong. Walk graph.get_state_history(config) backwards until the state looks correct, and the step after that is your culprit. You now know which node to read.

Then watch it happen. Re-run with stream_mode="updates" and you see each node's return value as it is produced, keyed by node name. A wrong branch shows up as a node you did not expect to see.

Only then look at the shape. print(graph.get_graph().draw_mermaid()) catches the mistakes that are invisible in code: an edge to the wrong node, a missing path to END, a branch whose declared destinations do not match what the router actually returns.

If all five pass and the behaviour is still wrong, the problem is probably in a model call rather than in the graph, and tracing is the tool for that: the graph did exactly what you wired it to do, and the prompt or the tool description is where the fault lies. Knowing which of the two layers you are debugging is half the work, and this sequence is what tells you.

Two last notes on things that are easy to get wrong because the documentation moves faster than the stable API. The default output version is still "v1", so invoke returns a plain dict and a pause shows up under result["__interrupt__"]; "v2" with its typed GraphOutput is opt-in. And stream_events(..., version="v3") appears in current docs pages described as recommended, but it is labelled beta — build on stream until you have a reason not to.

If you are on Python 3.10, one extra item for the list: get_stream_writer() does not work inside async nodes, because context does not propagate into asyncio tasks before 3.11. Take a writer parameter instead and pass config explicitly into async model calls. Starting a new project on 3.12 avoids the whole question.

This is part two of three. It assumes you can already build a StateGraph, wire edges, compile it and run it with a checkpointer. From here on we go after the mechanism: what the runtime actually does between your nodes, where state physically lives, and which knobs change behaviour under load. Everything below was checked against LangGraph 1.2.12 (released 21 September 2026).

Where this picks up

Each section says what problem it solves before it shows code, and most end with a Try it you can do against a graph you already have.

The Pregel loop, one super-step at a time

Almost every surprising thing LangGraph does becomes obvious once you hold the execution model in your head. LangGraph is not a function-call tree and not a DAG runner in the Airflow sense. It is an implementation of Pregel, Google's bulk-synchronous graph-processing model, with ideas from Apache Beam and an API shaped like NetworkX.

A run proceeds in super-steps. At the start of a super-step the runtime looks at which channels were written in the previous step and works out which nodes those writes have triggered. Every triggered node then runs — concurrently, if there is more than one — reading the state as it stood at the beginning of the step. None of them sees another's output. When the last of them finishes, the runtime collects all their returned dictionaries and applies them to the channels together, passing each key through its reducer. That application is the step boundary, and a checkpoint is written there. Then the loop repeats until no node is triggered, which is how END ends a run.

Three practical consequences follow, and they explain most of the questions mid-level engineers ask.

Parallel nodes cannot see each other's writes. If you fan out to three enrichment nodes, none of them can read what the others produced; they all read the pre-step state. If you need one to consume another's output, that is a second super-step, which means an edge, not a wish.

Writes are merged, not sequenced. Two nodes in the same step writing the same key is a collision, and the runtime refuses to guess:

InvalidUpdateError: At key 'score': Can receive only one value per step. Use an Annotated key to handle multiple values.
For troubleshooting, visit: https://docs.langchain.com/oss/python/langgraph/errors/INVALID_CONCURRENT_GRAPH_UPDATE

That error is not a bug in your graph structure. It is the runtime telling you the key has no reducer and therefore no defined merge. Either add one, or stop writing the key from two places.

The unit of progress is the step, not the node. This is why nodes re-execute from the top when a run resumes: the smallest thing the checkpointer knows how to restart from is a step boundary, so anything your node did before it paused or failed happens again. Every side effect inside a node must be idempotent or must live behind its own node.

Returning a Command instead of a plain dict lets a node combine an update with a routing decision, which is useful when the destination depends on data the node just computed and you would otherwise need a conditional edge that recomputes it. Command(update=..., goto="review") is one object doing both jobs. Pass destinations= to add_node so the rendered diagram still shows the possible edges, because a goto buried in Python is invisible to draw_mermaid().

For dynamic fan-out, Send(node, arg) returned from a conditional edge starts one copy of the target node per item, each with its own input rather than the shared state. That is the map half of map-reduce; the reduce half is a reducer on the key those copies write.

Channels and reducers beyond add_messages

Every key in your state schema is backed by a channel, a storage slot with a merge rule. The default channel is LastValue: it holds one value and the newest write overwrites it. That is why a plain str key behaves like a variable, and why two writers in one step are an error — LastValue has no way to pick.

A reducer replaces that rule. You declare it in the annotation, and the runtime calls reducer(current, update) at the step boundary:

import operator
from typing import Annotated
from typing_extensions import TypedDict

def merge_scores(current: dict, update: dict) -> dict:
    return {**current, **update}

class State(TypedDict):
    query: str                                   # LastValue: overwritten
    docs: Annotated[list, operator.add]          # appended
    scores: Annotated[dict, merge_scores]        # shallow-merged

The trap that costs people an afternoon: returning an empty value through a merging reducer does not clear the key. {"docs": []} through operator.add is a no-op, because concatenating an empty list changes nothing. The reducer is the only thing that touches the channel, so to bypass it you must say so explicitly:

from langgraph.types import Overwrite

def reset(state: State):
    return {"docs": Overwrite([])}     # replaces the channel, ignores the reducer

add_messages is the reducer you already use, and it is worth knowing precisely what it does, because it is more than an append. It appends new messages, replaces an existing message when the incoming one has the same ID, and accepts either message objects or plain dicts like {"role": "user", "content": "hi"}. The replace-by-ID behaviour is what lets you edit or redact a message in history: construct a message with the ID you want to overwrite and return it. MessagesState is simply a prebuilt TypedDict with messages: Annotated[list[AnyMessage], add_messages].

Two more channel types matter at this level. UntrackedValue holds state that is never checkpointed — the right home for an open client object or a large intermediate blob you do not want serialised into every checkpoint. And DeltaChannel, which is beta in 1.2, stores per-step deltas instead of a full value and takes a batch reducer plus snapshot_frequency=K:

class State(TypedDict):
    messages: Annotated[list, DeltaChannel(batch_reducer, snapshot_frequency=5)]

Its reducer receives (current, writes_sequence) rather than a single update, and the runtime forces a full snapshot after LANGGRAPH_DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT super-steps (default 5000). The reason to reach for it is checkpoint size on very long threads, which we come back to under cost.

Finally, a graph can have different schemas on its edges and its insides. StateGraph(State, input_schema=In, output_schema=Out) lets you accept a narrow input, keep scratch keys private, and return only what callers should see. Pydantic models work as state and give you runtime validation, at the cost of validation on every step; TypedDict is the common choice and a dataclass sits in between when you want real defaults.

Checkpoints, threads and what a snapshot holds

Persistence in LangGraph is one idea with a lot of leverage: at every step boundary the configured checkpointer saves the whole state as a checkpoint, keyed by thread_id. Short-term memory, human-in-the-loop, time travel, and crash recovery are all the same mechanism seen from different angles. No checkpointer means none of them.

A thread is just the sequence of checkpoints under one thread_id, which you pass in config:

config = {"configurable": {"thread_id": "support-4821"}}
graph.invoke({"messages": [{"role": "user", "content": "where is my order?"}]}, config)

Omit it and you get a blunt, useful error:

ValueError: Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_id

What you get back from graph.get_state(config) is a StateSnapshot, and reading it fluently is the single most useful debugging skill at this level. Its fields are values (the state), next (the nodes about to run — an empty tuple means the run finished), config (carrying thread_id, checkpoint_ns and checkpoint_id), metadata (including source, which is "input", "loop" or "update", plus writes and step), created_at, parent_config, and tasks. Each entry in tasks is a PregelTask with id, name, error and interrupts, which is where a failed or paused node confesses what happened.

checkpoint_ns identifies which graph the checkpoint belongs to; the root graph uses "" and subgraphs get their own namespace. You will see it the first time you pass subgraphs=True and wonder why there are two snapshots.

For anything beyond a notebook, swap InMemorySaver for a real backend. InMemorySaver (also exported as MemorySaver) keeps everything in RAM and loses it all when the process exits, which is fine for tests and wrong for a service.

from langgraph.checkpoint.postgres import PostgresSaver

with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
    checkpointer.setup()                 # REQUIRED once: creates the tables
    graph = builder.compile(checkpointer=checkpointer)

Three things bite here. setup() is not optional on first use, and skipping it gives you a missing-table error that reads like a permissions problem. The async savers (AsyncPostgresSaver, AsyncSqliteSaver) exist and must be paired with ainvoke/astream — mixing a sync saver into an async server is the usual cause of blocking-I/O warnings. And thread_id values longer than 255 characters fail at the database level, so use a UUID or a hash rather than concatenating user identifiers. For local development SqliteSaver.from_conn_string("checkpoint.db") gives you durability without infrastructure. MongoDB, Redis, Azure Cosmos DB and Oracle backends are also documented and installed as separate packages.

Durability: what you are paying for safety

Because a checkpoint is written at every step boundary, when that write is flushed is a real performance decision, and 1.x exposes it as one argument. The old checkpoint_during=True/False is deprecated; passing both raises Cannot use both checkpoint_during and durability parameters.

graph.invoke(payload, config, durability="sync")

There are three modes. "exit" persists only when the run exits: fastest, and no mid-run crash recovery — if the process dies halfway, that run's progress is gone. "async" is the default: the checkpoint is written while the next step runs, so you pay almost nothing but carry a small risk of losing the last step if the host dies at the wrong moment. "sync" writes the checkpoint before the next step begins, which is the safest and the slowest.

Choose by what a lost step costs. A batch enrichment job that can be re-run wants "exit". A conversational agent is fine on the default. A workflow that charges a card, files a ticket or sends a message to a customer wants "sync", because "we lost the step that recorded the charge" is a much worse outcome than a few milliseconds per step. The same reasoning applies to a graph that pauses for human approval: if the approval is the expensive part, you do not want to discover the pause was never persisted.

Durability interacts with idempotency rather than replacing it. Even on "sync", a node that fails after calling a payment API will re-run that call on resume, because resumption restarts the node from the top. Durability decides how far back you restart; idempotency decides whether restarting is safe. The pattern that solves it is to put each irreversible side effect in its own small node, so the restart window around it is as narrow as possible, and to pass an idempotency key derived from state rather than generated inside the node.

One more mechanic worth knowing: pending writes. If three nodes run in a step and one fails, the successful nodes' writes are stored as pending writes against the checkpoint, so on resume those nodes do not re-run. Only the failed one does. This is why a partially failed fan-out does not duplicate the work that succeeded.

Interrupts that survive a real approval queue

interrupt(value) pauses a run inside a node, persists the state, and surfaces the payload to the caller. It needs a checkpointer and a thread_id. You resume by invoking with Command(resume=value) on the same thread, and that value becomes the return value of the interrupt() call — execution continues from the line after it, in a node that has re-run from the top.

from langgraph.types import interrupt, Command

def approve_refund(state: State):
    decision = interrupt({"question": "Approve refund?", "amount": state["amount"]})
    if decision["approved"]:
        return {"status": "approved", "approver": decision["by"]}
    return {"status": "rejected"}

How you read the pause depends on the output version. With the default version="v1" the payload is at result["__interrupt__"]. With version="v2" it is result.interrupts on the returned GraphOutput. With the beta v3 event API it is run.interrupts, and run.interrupted tells you whether a pause happened at all. Pick one and be consistent, because the dict-style access on a v2 GraphOutput is deprecated and planned for removal.

New in 1.2.12, you can declare the shape of what you expect back:

from pydantic import BaseModel

class Decision(BaseModel):
    approved: bool
    by: str

decision = interrupt({"question": "Approve refund?"}, response_schema=Decision)

The resume value is then validated and returned as that type. This matters more than it sounds: the resume value usually arrives from a web form or a Slack action, which is exactly where malformed payloads come from, and without a schema a typo surfaces as a KeyError deep inside the node after the side effects above it have already re-run.

The official rules are short and all of them are learned the hard way:

• Never wrap interrupt() in try/except. It works by raising GraphInterrupt, so a bare except Exception: silently swallows the pause and your run continues as if nothing happened.
• Do not reorder interrupt() calls within a node. Resumes are matched by order, so inserting one above another misroutes the values.
• Make everything above an interrupt() idempotent. The node re-runs from the top on resume, so a notification sent before the pause is sent twice.
• Keep payloads small and JSON-serialisable. They are persisted and travel over HTTP.

When a step produces several pauses at once — a fan-out where each branch needs sign-off — you resume them together with a mapping from interrupt ID to value: Command(resume={interrupt_id: value, ...}). Read the IDs from Interrupt.id (the old interrupt_id attribute is deprecated).

Static breakpoints are a different tool for a different job. interrupt_before=["call_model"] and interrupt_after=[...], set at compile or at invoke time, stop the graph around a node without changing its code. They are for inspecting a graph while you debug, not for building approval flows.

Time travel: replay, fork, and the debugging loop

Because every step is checkpointed, a thread is a history you can walk. graph.get_state_history(config) returns snapshots newest first, each carrying the checkpoint_id that identifies it. From any of them you can do one of two distinct things, and confusing them wastes time.

Replay means invoking with a prior checkpoint's config. Everything up to that checkpoint is loaded from storage rather than recomputed, and everything after it executes again:

history = list(graph.get_state_history(config))
target = history[3].config          # includes checkpoint_id
graph.invoke(None, target)          # re-runs from that point

Fork means changing the past before re-running it. graph.update_state(prior_config, values, as_node="classify") writes a new checkpoint whose parent is the one you named, with your values applied as if that node had produced them — which matters, because the as_node argument determines which edges fire next. Then graph.invoke(None, forked_config) runs forward along the new branch. The original branch is untouched, so you can compare outcomes.

That pair is the production debugging loop. A user reports that an agent gave a wrong answer on thread support-4821. You pull the history, find the step where the router chose the wrong branch, fork with a corrected routing key, and replay forward to see whether the rest of the graph would have recovered. No prompt guesswork, no reproducing the conversation by hand. Studio in LangSmith gives you the same operations through a UI over a deployed graph.

Two details to keep in mind. Interrupts are always re-triggered on replay, so a forked run through an approval node will stop and wait again — expected, occasionally startling. And forking also tells you whether a bug is in the model or in your graph: if the forked run with corrected state behaves, your prompts are fine and your routing is not.

Long-term memory with the Store

A checkpointer gives a thread memory of itself. It gives you nothing across threads, which is the wrong shape for "remember that this user prefers Arabic" or "we already know this customer's plan tier". That is what the Store is for: a long-term, cross-thread key-value memory organised by namespace tuples.

from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
graph = builder.compile(checkpointer=checkpointer, store=store)

def remember(state: State, runtime: Runtime[Ctx]):
    ns = (runtime.context.user_id, "memories")
    runtime.store.put(ns, "lang", {"preferred_language": "ar"})
    hits = runtime.store.search(ns, query="language preference", limit=5)
    return {"notes": [h.value for h in hits]}

The operations are put, get, search, delete and list_namespaces. search defaults to a limit of 10 and takes an offset, so paginate rather than assuming you got everything. Namespaces are tuples and are matched by prefix, which is what makes them the natural isolation boundary: put the tenant first, then the user, then the category, and list_namespaces(prefix=("tenant-a",), max_depth=2) tells you what exists under a tenant without scanning.

Semantic search is opt-in and configured when you build the store:

store = InMemoryStore(index={
    "embed": init_embeddings("openai:text-embedding-3-small"),
    "dims": 1536,
    "fields": ["preferred_language", "notes"],
})

PostgresStore is the production counterpart, and like the Postgres checkpointer it needs setup() the first time. On the Agent Server, the store is configured in langgraph.json instead of in code, including ttl settings where default_ttl is in minutes and refresh_on_read defaults to true.

Reach for runtime.store inside nodes rather than closing over a module-level object: when the graph is deployed, the server injects the store, and a node that uses the injected handle works unchanged in both places. The same applies to writing memories at all — be deliberate. A graph that writes a memory on every turn builds a namespace full of near-duplicates that then pollute every search. Extract memories in a dedicated node, with a rule about what is worth keeping, and let search surface the few that matter. If you want model-judged extraction quality rather than vibes, that is an evaluation problem: see /student-guides/ragas.

Subgraphs and their three persistence modes

A compiled graph is a Runnable, so it can be a node in another graph. That is how you keep a large agent comprehensible: one graph per concern, composed. There are two ways to attach one, and the choice is about schemas. If the subgraph's state shares keys with the parent, add it directly as a node and the shared keys flow both ways. If the schemas differ, wrap it in a function node that translates in and out — which is also where you put any filtering you want, since it is the only place you control what crosses the boundary.

researcher = research_builder.compile()                 # per-invocation persistence

def run_research(state: ParentState):
    out = researcher.invoke({"question": state["query"]})
    return {"findings": out["summary"]}

parent.add_node("research", run_research)

The part people miss is that the subgraph's checkpointer= argument changes its memory semantics, and the three values mean genuinely different things:

True is what you want for a sub-conversation that should remember earlier turns, and it is also how you earn the MULTIPLE_SUBGRAPHS error: calling the same checkpointer=True subgraph more than once inside a single node is rejected, because there is one checkpoint namespace to write to and two callers. The fixes are to use False, to omit the argument, or to wrap each call in its own uniquely named node.

When you stream or inspect, pass subgraphs=True to see inside: graph.stream(payload, config, subgraphs=True) tags each event with its namespace, and graph.get_state(config, subgraphs=True) returns the nested snapshots. Without it, a subgraph looks like one opaque node — fine in production logs, useless when debugging.

One asymmetry to remember from the fault-tolerance section below: defaults you set with set_node_defaults() are resolved at compile() time and are not inherited by subgraphs. Each subgraph declares its own.

Retries, caching and per-node timeouts

Agent graphs call networks, and networks fail. LangGraph gives you per-node policies so you do not scatter retry loops through your business logic.

from langgraph.types import RetryPolicy, CachePolicy, TimeoutPolicy
from langgraph.cache.memory import InMemoryCache

builder.add_node(
    "call_model", call_model,
    retry_policy=RetryPolicy(max_attempts=3, initial_interval=0.5,
                             backoff_factor=2.0, max_interval=128.0, jitter=True),
    cache_policy=CachePolicy(ttl=3),
    timeout=TimeoutPolicy(run_timeout=120, idle_timeout=30),
)
graph = builder.compile(checkpointer=checkpointer, cache=InMemoryCache())

Those RetryPolicy values are the defaults, so RetryPolicy() is already a sensible exponential backoff with jitter. The important part is what it retries. The default retry_on retries any exception except a list of programmer errors: ValueError, TypeError, ArithmeticError, ImportError, LookupError, NameError, SyntaxError, RuntimeError, ReferenceError, StopIteration, StopAsyncIteration and OSError. For requests and httpx errors it retries only on 5xx. That is the right default: retrying a 400 from a model provider three times with backoff just makes the same mistake slower. If you have a custom exception that is transient, pass it in retry_on explicitly.

Caching needs both halves — a cache_policy on the node and a cache= on compile() — and a node with no cache configured on the graph silently runs every time. The natural candidates are deterministic, expensive, repeated calls: an embedding of the same query, a schema lookup, a retrieval step you hit several times while iterating on a prompt. ttl is in seconds.

Timeouts arrived in 1.2 and have one hard constraint:

ValueError: Node timeouts are only supported for async nodes because sync Python execution cannot be safely cancelled in-process. Node 'a' is sync.

So timeout= requires async def. TimeoutPolicy distinguishes run_timeout (total wall clock for the node) from idle_timeout (time with no activity), and NodeTimeoutError tells you which fired via .kind, along with .node and .elapsed. Writes from a timed-out attempt are discarded, and NodeTimeoutError is retryable, so a TimeoutPolicy plus a RetryPolicy gives you "give up on this attempt after 30 idle seconds and try again" in two lines. An async-generator node can yield {} as a heartbeat to reset idle_timeout during long legitimate work. timeout= also accepts a plain float or a timedelta.

Also in 1.2: a node-level error_handler=, a callable taking (state, error: NodeError) and returning a dict or a Command, which lets you route a failure to a fallback branch instead of killing the run. There is one handler per node, a failing handler propagates, and interrupt() bypasses handlers entirely — it is a pause, not an error. builder.set_node_defaults(retry_policy=..., timeout=..., cache_policy=..., error_handler=...) sets the baseline for the graph, with per-node arguments overriding it.

Streaming what a user should actually see

A graph that takes twenty seconds and returns one blob feels broken. Streaming is how you fix that, and the thing to internalise is that LangGraph streams several different things, selected by stream_mode.

for chunk in graph.stream(payload, config, stream_mode=["updates", "messages", "custom"]):
    ...

values yields the full state after each step — simple, and heavy once state is large. updates yields only what each node returned, which is usually what a UI wants. messages yields LLM tokens as (chunk, metadata) pairs, and the metadata is how you tell which node produced them when two nodes both call models. custom carries whatever you write yourself, which is the mode most teams underuse:

from langgraph.config import get_stream_writer

def retrieve(state: State):
    writer = get_stream_writer()
    writer({"status": "searching the knowledge base"})
    docs = search(state["query"])
    writer({"status": f"found {len(docs)} documents"})
    return {"docs": docs}

That is how you turn dead air into progress. checkpoints, tasks and debug exist too and are for your own diagnostics rather than a user interface.

On Python 3.10, get_stream_writer() does not work in async nodes, because context does not propagate into asyncio tasks before 3.11. The same limitation is why you must pass config explicitly into model.ainvoke(..., config) on 3.10. If you are choosing a runtime, 3.11 or later removes a whole class of these problems — and the Agent Server requires 3.11 anyway.

LangGraph 1.2 also introduced a separate, beta event API:

run = graph.stream_events(payload, config, version="v3")
for part in run.messages:
    print(part.text, end="")
print(run.output)

stream_events returns a GraphRunStream (async: astream_events → AsyncGraphRunStream) with built-in projections: run.values, run.messages (one ChatModelStream per LLM call, exposing .text, .reasoning, .tool_calls, .usage and .output), run.lifecycle, run.subgraphs, plus run.output, run.interrupted and run.interrupts. Projections are single-consumer, so use .tee(n)/.atee(n) or run.interleave("messages", "values") if two parts of your code need the same stream. .usage on the messages projection is the cheapest honest token counter you will get without a tracing backend.

Note the version landscape, because it is easy to misread the docs. The default for invoke and stream is still version="v1"; version="v2" is opt-in and gives you typed StreamPart dicts and a GraphOutput. The v3 label belongs only to stream_events. Current docs pages write their examples with stream_events(..., version="v3") and call it recommended, but it is still labelled beta — and content-block streaming with it requires v3 end to end, inner graphs included. For production today, multi-mode stream() is the conservative choice; adopt v3 where you need its projections and accept that beta means the surface can move.

Testing a graph you can trust

Graphs look hard to test and are not, once you stop trying to test them end to end. The official guidance is three techniques at three granularities.

Test a node in isolation. Nodes are functions from state to a partial update, which makes them ordinary unit-test targets. A compiled graph also exposes them:

def test_classify_routes_billing():
    out = graph.nodes["classify"].invoke({"query": "my card was charged twice"})
    assert out["intent"] == "billing"

Test structure and routing without models. Compile the real graph with stub nodes, or stub the model, and assert the path taken. graph.get_graph().draw_mermaid() is also a test artifact: committing it means a reviewer sees routing changes in the diff.

Test from the middle. This is the technique worth stealing. Rather than driving a long graph from the start to reach the interesting state, write the state you want and start there:

import pytest
from langgraph.checkpoint.memory import InMemorySaver

@pytest.fixture
def graph():
    return builder.compile(checkpointer=InMemorySaver())   # fresh per test

def test_escalation_path(graph):
    config = {"configurable": {"thread_id": "t1"}}
    graph.update_state(config, {"intent": "billing", "attempts": 3}, as_node="classify")
    result = graph.invoke(None, config, interrupt_after=["escalate"])
    assert graph.get_state(config).next == ("notify_human",)

A fresh graph with a fresh InMemorySaver per test matters: a shared saver leaks threads between tests and produces failures that depend on ordering. interrupt_after=[...] at invoke time bounds the run so one test covers one hop.

What you still cannot assert cheaply is model output quality. Keep that out of your unit suite and put it behind evaluation, where a small dataset and graded metrics are the right tools — /student-guides/langsmith and /student-guides/langfuse both do this, and /student-guides/promptfoo is the lighter-weight option for prompt-level regression checks in CI. In your pytest suite, assert on structure, routing, state transitions and tool calls — the things that are deterministic and the things that actually break when someone edits the graph.

Running it: the Agent Server, or your own service

At some point the graph has to be a service, and there are two honest paths.

Path one: the Agent Server. You describe the app in langgraph.json and the server handles threads, runs, queuing, streaming, crons and interrupts over HTTP.

{
  "dependencies": ["."],
  "graphs": { "agent": "./my_agent/agent.py:graph" },
  "env": ".env",
  "python_version": "3.12",
  "api_version": "0.15",
  "store": { "ttl": { "default_ttl": 43200, "refresh_on_read": true } },
  "checkpointer": { "ttl": { "strategy": "keep_latest", "default_ttl": 20160 } }
}

Both default_ttl values are in minutes, which is the single most misread field in that file. api_version pins the Agent Server minor so a redeploy does not quietly move you to a newer server. graphs points at either a compiled graph variable or a factory function; the variable is recommended because it is loaded once, whereas a factory runs per request.

The one rule that catches everyone migrating from scripts: do not configure a checkpointer or store in code for an Agent Server deployment. The server injects them, and your hand-rolled PostgresSaver either fights it or quietly creates a second set of tables. Guard it with an environment check, or keep deployment wiring out of the graph module entirely.

Locally:

pip install -U "langgraph-cli[inmem]"     # quote the extras in zsh
langgraph dev                             # http://127.0.0.1:2024, /docs for OpenAPI
curl http://127.0.0.1:2024/ok             # {"ok":true}

langgraph dev needs no Docker and needs Python 3.11+. For a Docker-backed local server, langgraph build -t my-agent then langgraph up -p 8123, or langgraph dockerfile -c langgraph.json Dockerfile if you want to own the build in your existing CI. Pass --platform linux/amd64,linux/arm64 to build when your laptop and your cluster disagree about architecture.

Architecturally, the server is API replicas plus queue workers over PostgreSQL and Redis. Postgres holds assistants, threads, runs, crons, checkpoints and the store; Redis is pub/sub, cancellation and streaming signalling only, holds nothing durable, and can be lost without data loss. Runs are created as pending rows in Postgres, announced through Redis, leased by a worker, executed and checkpointed, with events flowing back through Redis to SSE. The queue enforces at most one active run per thread — which is why a second message arriving mid-run needs a multitask_strategy: enqueue (default), reject, interrupt or rollback.

An assistant is a versioned configuration of a deployed graph — graph ID plus config and context. That is the right mechanism for per-tenant prompt or model variations: one graph, many assistants, rather than a graph per customer.

Talk to it with the SDK:

from langgraph_sdk import get_client

client = get_client(url="http://localhost:2024")
thread = await client.threads.create()
async for chunk in client.runs.stream(thread["thread_id"], "agent",
                                      input={"messages": [{"role": "user", "content": "hi"}]},
                                      stream_mode="updates"):
    print(chunk)

Or make a deployed graph look local with RemoteGraph (from langgraph.pregel.remote import RemoteGraph), which can even be used as a subgraph inside another graph — a clean way to split a large system across teams and deployments.

Path two: embed the library. Import LangGraph into your own FastAPI service with a PostgresSaver and skip the Agent Server. You then own queuing, per-thread concurrency, streaming plumbing and authentication. Choose this when you already have a platform with those answers and want one fewer moving part; choose the Agent Server when you do not, because reimplementing "one run per thread, resumable, with SSE" is more work than it looks. If you go the embedded route, the usual stack is /student-guides/fastapi in /student-guides/docker on /student-guides/kubernetes, with /student-guides/helm or /student-guides/argo-cd doing the deploying.

Three operational facts to carry into either path. N_JOBS_PER_WORKER defaults to 10 concurrent runs per worker, and throughput scales roughly linearly with workers. LANGGRAPH_POSTGRES_POOL_MAX_SIZE defaults to 150 per replica, so ten replicas can ask Postgres for 1500 connections — size the database accordingly or put a pooler in front. And on hosted deployments an HTTP connection is capped at one hour, so long runs must be rejoined with POST /threads/{thread_id}/runs/{run_id}/stream rather than held open.

Observability, and the tools next door

The library's own diagnostics go a long way. config["metadata"] inside a node carries langgraph_step, langgraph_node, langgraph_triggers, langgraph_path and langgraph_checkpoint_ns, which means your structured logs can say exactly where in which graph a line came from. Logging langgraph_step also lets you handle a runaway loop proactively, before it hits the limit.

Speaking of which, set recursion_limit yourself. The defaults in 1.x are deliberately high — the docs say 1000 from 1.0.6, and the installed 1.2.12 code uses 10007, overridable with LANGGRAPH_DEFAULT_RECURSION_LIMIT. A high default is friendly to legitimate long graphs and unfriendly to your token budget when a router forgets to return END:

graph.invoke(payload, {"configurable": {"thread_id": "t1"}, "recursion_limit": 50})

For traces, LANGSMITH_TRACING=true plus LANGSMITH_API_KEY (and optionally LANGSMITH_PROJECT) gives you every node, model call and tool call with inputs and outputs. From 1.2.10 you can shape what is captured per node with trace_policy= on add_node, which is how you keep a node handling personal data out of traces, alongside config metadata/tags and LangSmith's anonymizers. LANGSMITH_TRACING=false turns it all off, and LANGGRAPH_CLI_NO_ANALYTICS=1 opts out of CLI analytics.

If your organisation standardises on something else, the Agent Server supports Datadog via DD_API_KEY (it wraps the process with ddtrace-run, which can conflict with OpenTelemetry) and OTel APM via LS_APM_OTEL_ENABLED, with LOG_LEVEL, LOG_JSON and LOG_COLOR for logs. /student-guides/langfuse is the open-source alternative for LLM-specific tracing, and /student-guides/opentelemetry is the neutral layer if you want agent traces in the same backend as the rest of your services. For the model layer itself, /student-guides/litellm in front of your providers gives you one place for keys, routing and spend limits, which keeps provider churn out of the graph.

Two secrets rules, because checkpoints and traces are both durable copies of your state. Never put a secret in graph state — it will be persisted and very likely traced. And prefer the identity that @auth.authenticate returns, which flows into run context, over per-user tokens carried in state. Local .env files referenced from langgraph.json are fine for development and are not a deployment mechanism.

Debugging beyond the basics

A short field guide to the failures that are specific to this level, and what each one is really telling you.

INVALID_GRAPH_NODE_RETURN_VALUE — Expected dict, got ['whoops']. A code path returned something that is not a dict of state keys (or a Command). Usually an early return that forgot the wrapper, or an implicit None. Every path returns a dict.

ValueError: Graph must have an entrypoint: add at least one edge from START to another node and ValueError: Found edge ending at unknown node 'nope'. Both come from compile(), which validates structure. The second is normally a typo or a node added under a different name than the edge expects; remember that add_node(fn) names the node after the function.

INVALID_CHAT_HISTORY from create_agent. An AIMessage with tool_calls has no matching ToolMessage. The classic cause is resuming a paused or errored agent by invoking with a fresh HumanMessage, which appends to a dangling tool call. Resume with None or Command(resume=...), or update_state to remove the dangling calls.

Blocking-I/O warnings under langgraph dev or the Agent Server. The ASGI server detects synchronous blocking calls inside async code. The real fix is async clients (httpx.AsyncClient, psycopg async, async model SDK calls) or asyncio.to_thread. langgraph dev --allow-blocking silences it for local development only, and BG_JOB_ISOLATED_LOOPS=True in a deployment stops health checks failing without fixing the cause.

Deprecation warnings you should act on rather than filter. MessageGraph is deprecated and slated for removal in 2.0 — use StateGraph with a messages key. from langgraph.constants import Send should be from langgraph.types import Send (START and END are fine from either). config_schema= is now context_schema=, with the Runtime[Ctx] node parameter replacing config["configurable"] for dependencies. create_react_agent from langgraph.prebuilt is deprecated in favour of create_agent from langchain.agents, where prompt= became system_prompt=. And langgraph-supervisor is no longer actively maintained; the documented replacement is the subagents pattern, where a create_agent has tools that wrap worker agents.

Studio will not open. In Safari or on restrictive networks, langgraph dev --tunnel. If a self-hosted setup fails to authenticate, check LANGSMITH_ENDPOINT for a trailing slash, which breaks it.

The deployment-specific trap worth planning for: LangGraph applies the latest deployed code to all threads, including in-flight ones. Adding, removing or rerouting edges is safe. Adding state keys is safe if they are NotRequired or optional. Renaming or removing a node while threads are paused at it is not — those threads cannot resume. Nor is renaming a state key, which loses its contents, or narrowing a type. The practical pattern is add-then-remove across two releases, with a thread search on status=interrupted|busy to confirm nothing is waiting at the node you are about to delete. For business-logic changes, stamp a flow_version into state when a thread starts and branch on it, so old threads finish the way they began.

Putting it all together

Here is a document-approval graph that uses most of this level at once: a reducer, a real checkpointer, a typed interrupt, a retry policy, a timeout, custom streaming, and an explicit recursion limit.

import operator
from typing import Annotated
from typing_extensions import TypedDict
from pydantic import BaseModel

from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, Command, RetryPolicy, TimeoutPolicy
from langgraph.config import get_stream_writer

class State(TypedDict):
    doc_id: str
    findings: Annotated[list, operator.add]
    status: str

class Decision(BaseModel):
    approved: bool
    by: str

async def analyse(state: State):
    writer = get_stream_writer()
    writer({"status": "analysing document"})
    findings = await review_document(state["doc_id"])     # your async call
    return {"findings": findings}

def gate(state: State):
    decision = interrupt(
        {"doc_id": state["doc_id"], "findings": state["findings"]},
        response_schema=Decision,
    )
    return Command(
        update={"status": "approved" if decision.approved else "rejected"},
        goto="publish" if decision.approved else END,
    )

def publish(state: State):
    return {"status": "published"}

builder = StateGraph(State)
builder.add_node("analyse", analyse,
                 retry_policy=RetryPolicy(max_attempts=3),
                 timeout=TimeoutPolicy(run_timeout=120, idle_timeout=30))
builder.add_node("gate", gate, destinations=("publish", END))
builder.add_node("publish", publish)
builder.add_edge(START, "analyse")
builder.add_edge("analyse", "gate")
builder.add_edge("publish", END)

Wire it to Postgres and run it:

from langgraph.checkpoint.postgres import PostgresSaver
from app.graph import builder

with PostgresSaver.from_conn_string(DB_URI) as cp:
    cp.setup()
    graph = builder.compile(checkpointer=cp)

    config = {"configurable": {"thread_id": "doc-991"}, "recursion_limit": 50}
    result = graph.invoke({"doc_id": "doc-991", "findings": [], "status": "new"},
                          config, durability="sync")
    print(result["__interrupt__"])           # the gate is waiting

    # ... later, from your approval UI
    graph.invoke(Command(resume={"approved": True, "by": "aya"}), config,
                 durability="sync")

Walk the decisions. findings carries a reducer because analyse may one day fan out, and a reducer costs nothing to add now and a migration to add later. analyse is async def because timeout= requires it, and it gets both a retry and a timeout so a hung provider call fails fast and is retried rather than holding the run forever. The interrupt payload is small and JSON-serialisable, and response_schema=Decision means a malformed resume from the UI is rejected at the boundary rather than deep inside gate. gate returns a Command because it decides both state and route, with destinations= keeping the rendered diagram honest. durability="sync" is right here because the approval is the expensive artifact. And recursion_limit is set explicitly, because the default in 1.2.12 is 10007 and nobody wants to find that out from a bill.

To put this behind HTTP, add a langgraph.json pointing at app/graph.py:graph — and delete the compile-time checkpointer from the deployed module, because the server injects its own.

Where you are now

You can predict what a LangGraph run will do. You know that execution proceeds in super-steps, that parallel nodes read the pre-step state and have their writes merged through reducers, and that a checkpoint is written at every step boundary. You know what that checkpoint contains, where it lives, how to inspect it with get_state and walk it with get_state_history, and how to change the past with update_state and re-run it. You know why nodes re-run from the top on resume and what that demands of your side effects.

You can also make the thing survive contact with production: a real checkpointer with setup() called, a durability mode chosen on purpose, retries that do not retry programmer errors, timeouts on async nodes, a Store for cross-thread memory with namespaces that isolate tenants, and streaming that tells a user something is happening. You can test the parts that are deterministic without paying a model to run, and you know which migrations will break a paused thread before you ship them.

What is left for the senior level is ownership rather than usage: the architecture of the Agent Server under real concurrency and which component gives out first, the authentication model that makes a self-hosted server safe for more than one tenant, encryption of checkpoints at rest, custom checkpointers, graceful drains with RunControl, cost control through DeltaChannel and TTL strategies, and the judgement call about where LangGraph stops being the right tool. The next natural step sideways is evaluation and observability, because a graph you cannot measure is a graph you cannot improve: /student-guides/langfuse for traces, /student-guides/ragas for retrieval quality, and /student-guides/langchain for the agent abstractions that sit on top of everything here.

Sources

• LangGraph overview
• Graph API
• Use the Graph API
• Pregel runtime
• Persistence
• Checkpointers
• Stores
• Add memory
• Durable execution
• Fault tolerance
• Interrupts
• Time travel
• Subgraphs
• Streaming
• Event streaming
• Testing
• Backward compatibility
• Observability
• Application structure
• Agent Server
• Scalability and resilience
• Double texting
• Configure TTL
• LangGraph CLI
• Common errors
• LangGraph v1 release notes

At this level an interviewer is not checking whether you can name StateGraph. They are checking whether you can predict what a graph will do under load, under failure, and under a resume — and whether you know which of your choices cost money. The questions below are the ones that actually get asked, with the reasoning a strong answer shows.

Scenario: the same side effect fires twice

"Users are getting two confirmation emails from an approval flow. Where do you look?"

Start from the execution model, not the email client. In LangGraph a node that pauses or fails re-executes from the top when the run resumes, because the smallest restartable unit is a super-step boundary. So the question becomes: is there a line above the pause that sends the email?

def gate(state):
    send_confirmation(state["email"])      # runs again on resume
    decision = interrupt({"doc": state["doc_id"]})
    ...

That is the bug, and it is the single most common interrupt mistake. There are two fixes and you should name both. The structural one is to move the side effect into its own upstream node, so that the node containing interrupt() does nothing irreversible. The defensive one is idempotency: derive an idempotency key from state — the thread ID plus the document ID, not a UUID generated inside the node — and let the downstream service deduplicate.

A strong answer adds the related trap: the same re-run semantics apply to a node that failed and was retried under a RetryPolicy, so this is not only an interrupt problem. A weak answer blames the mail provider.

Scenario: InvalidUpdateError on a key you thought was fine

"A fan-out worked in staging and throws At key 'score': Can receive only one value per step in production. Explain."

The error is structural, not environmental, so the first thing to say is that staging probably took a different branch. Nodes triggered in the same super-step run concurrently, and their writes are applied together at the step boundary through each key's reducer. A key with no reducer is backed by a LastValue channel, which holds one value and has no defined way to merge two. The runtime refuses to pick arbitrarily and raises INVALID_CONCURRENT_GRAPH_UPDATE.

So in staging, only one of the parallel nodes was reached — a router condition, a short-circuit, an empty input list for a Send fan-out. In production both fired.

The fix is one of two things, and choosing between them is the interesting part. Either the key genuinely holds contributions from several nodes, in which case give it a reducer — Annotated[list, operator.add], or a dict merge, or a custom function — or it does not, in which case one of those nodes should not be writing it, and adding a reducer would paper over a design error. Mention that you would also check whether a reducer already exists but the value shape is wrong: returning a bare dict into a key reduced by operator.add fails differently.

Scenario: the run never ends

"An agent loops until it dies. What do you check, and in what order?"

First, the router. A cycle with no exit means some conditional edge never returns END. Print the node sequence — stream_mode="updates" gives you it for free — and find the two nodes ping-ponging.

Second, the limit, and this is where candidates date themselves. Do not say the default is 25; that was pre-1.0.6. In 1.x the defaults are deliberately high: the docs say 1000 from 1.0.6, and in the installed 1.2.12 the code default is 10007 super-steps, overridable with LANGGRAPH_DEFAULT_RECURSION_LIMIT. The error reads Recursion limit of 10007 reached without hitting a stop condition. The operational point is that a high default means a runaway loop burns a lot of tokens before it stops, so you should always set recursion_limit explicitly in config for anything with a cycle:

graph.invoke(payload, {"configurable": {"thread_id": "t1"}, "recursion_limit": 50})

Third, proactive handling. config["metadata"]["langgraph_step"] is available inside nodes, so a router can check how deep it is and route to a graceful "I could not finish this" branch instead of waiting for an exception. That answer separates someone who has run an agent in production from someone who has read the quickstart.

Scenario: twenty seconds of silence

"The product team says the agent feels broken. It returns a correct answer in about twenty seconds."

This is a streaming question, and the strong answer distinguishes the modes rather than saying "use streaming". values gives you the whole state after each step, which is heavy once state is large. updates gives you only what each node returned, which is usually what a UI consumes. messages gives LLM tokens as (chunk, metadata) pairs, and the metadata is how you attribute tokens when two nodes both call models. And custom, written from inside a node with get_stream_writer(), is the one that fixes this complaint, because the dead air is usually a retrieval or tool step that produces no tokens at all:

writer = get_stream_writer()
writer({"status": "searching the knowledge base"})

You can pass a list: stream_mode=["updates", "messages", "custom"].

Then say what you would not change yet. Twenty seconds may be correct work; streaming changes the perception, and that is a legitimate fix. If the latency itself is the problem, the levers are different: cache_policy on deterministic repeated nodes with cache=InMemoryCache() on compile, durability="exit" to stop paying for a checkpoint write per step, and parallelising independent nodes into one super-step. Naming perception and latency as separate problems is the mark of a good answer.

Scenario: a bad answer on one thread, last Tuesday

"A customer complains about one conversation. You have the thread ID. How do you investigate?"

Because every super-step is checkpointed, the thread is a replayable history. Walk it with graph.get_state_history(config), which returns StateSnapshots newest first. Read metadata["step"], metadata["source"] ("input", "loop" or "update"), next, and tasks — a PregelTask carries error and interrupts, so a failed node confesses there.

Then distinguish the two operations, which is the actual test in this question. Replay is invoking with a prior checkpoint's config: everything before it is loaded from storage, everything after re-executes. Fork is graph.update_state(prior_config, values, as_node="router") followed by graph.invoke(None, forked_config) — you rewrite a value as if that node had produced it, which also determines which edges fire next, and run forward on a new branch while the original stays intact.

That gives you a clean experiment: fork with the routing key corrected and see whether the rest of the graph recovers. If it does, the bug is in your classification; if it does not, the bug is downstream. Add that interrupts are always re-triggered on replay, so an approval node will stop and wait again.

Trade-off: which durability mode

"Walk me through durability."

Three modes, one decision. "exit" persists only when the run exits — fastest, no mid-run crash recovery. "async" is the default: the checkpoint is written while the next step runs, so the cost is near zero and the risk is losing the last step if the host dies at the wrong instant. "sync" writes before the next step starts — safest, slowest.

Choose by what a lost step costs, and give concrete cases. A nightly batch enrichment that can be re-run: "exit". A chat assistant: the default. A flow that charges a card, files a ticket, or persists a human approval: "sync", because losing the step that recorded the approval is far worse than a few milliseconds.

The senior-sounding addition is that durability is not idempotency. Even on "sync", a node that fails after calling a payment API re-runs that call on resume, because resumption restarts the node from the top. Durability decides how far back you restart; idempotency decides whether restarting is safe. Also mention checkpoint_during= is deprecated in favour of durability=, and passing both raises.

Trade-off: Agent Server or your own service

"Would you deploy with the Agent Server or embed the library?"

Answer with the division of responsibility rather than a preference. The Agent Server gives you threads, runs, a queue that enforces at most one active run per thread, resumable SSE streaming, crons, assistants and an interrupt API over HTTP, on PostgreSQL plus Redis — Postgres holding assistants, threads, runs, crons, checkpoints and the store, Redis doing pub/sub, cancellation and streaming signalling only, with nothing durable in it. Embedding the library in your own FastAPI service with a PostgresSaver means you own all of that yourself.

So: if you already have a platform with answers for queuing, per-thread concurrency and auth, embedding is one fewer moving part. If you do not, reimplementing "one run per thread, resumable, with streaming" is more work than it looks.

Two details that show you have done it. The deployed graph module must not configure a checkpointer or store in code, because the server injects them. And a compiled graph variable in langgraph.json is recommended over a factory function, because the variable is loaded once while a factory runs per request.

Trade-off: when does a subgraph earn its keep

"When do you split a graph into subgraphs, and what does checkpointer= do there?"

Split for comprehensibility and for ownership boundaries, not because the graph has many nodes. The signal is a cluster of nodes with its own state keys that nobody outside reads.

Then the mechanics, which is what is really being asked. Attach the compiled subgraph directly as a node when its schema shares keys with the parent; wrap it in a function node when the schemas differ, which also gives you the only place to control what crosses the boundary. And the subgraph's own compile(checkpointer=...) sets its memory semantics: omitted or None is per-invocation — it inherits the parent checkpointer, starts fresh each call, and supports interrupts; True is per-thread, accumulating across calls and disallowing parallel calls; False is stateless.

True is also how you earn MULTIPLE_SUBGRAPHS: calling the same checkpointer=True subgraph twice inside one node is rejected, because there is one namespace and two callers. Fix with False, by omitting the argument, or by wrapping each call in its own named node. Finish with the debugging note: pass subgraphs=True to stream or get_state or the subgraph is one opaque node.

Trade-off: checkpointer memory versus Store memory

"The agent should remember a user's preferences. Checkpointer or Store?"

Store, and the reason is scope. A checkpointer gives a thread memory of itself, keyed by thread_id. The Store is cross-thread, long-term key-value memory organised by namespace tuples — (tenant_id, user_id, "memories") — with put, get, search, delete and list_namespaces, prefix matching on namespaces, a default search limit of 10, and optional semantic indexing via index={"embed": ..., "dims": ..., "fields": [...]}.

Say that namespaces are your isolation boundary in a multi-tenant product: tenant first, then user. Say you reach runtime.store inside nodes rather than closing over a global, so the same node works when a server injects the store. And say the thing most people get wrong, which is write discipline: a graph that writes a memory every turn fills a namespace with near-duplicates that then pollute every search, so extraction belongs in a dedicated node with a rule about what is worth keeping.

What strong answers have in common

Four habits separate the answers that land from the answers that are merely correct.

They start from the super-step. Concurrency, merge errors, re-run semantics, checkpoint frequency and resume behaviour are all the same mechanism. A candidate who explains the Pregel loop once can then derive five answers from it, instead of memorising five rules.

They name the version and the default. "The recursion limit default is high in 1.x — the docs say 1000, the 1.2.12 code uses 10007" is a different class of answer from "there's a recursion limit". The same applies to durability defaulting to "async", N_JOBS_PER_WORKER defaulting to 10, and LANGGRAPH_POSTGRES_POOL_MAX_SIZE defaulting to 150 per replica.

They separate the library from the deployment. Interrupts, reducers, checkpointers and durability are the open-source library. Assistants, double-texting strategies (enqueue, reject, interrupt, rollback), crons and the queue are Agent Server features. Candidates who blur the two cannot be trusted to scope a design.

They mention cost without being asked. A checkpoint is the full state at every super-step by default, so a long thread with a growing message list writes that list again and again. The levers are checkpoint TTLs (strategy: delete or keep_latest), durability="exit" where it is safe, UntrackedValue for keys that should never be persisted, and DeltaChannel (beta in 1.2) for the biggest keys. Mentioning this unprompted signals someone who has owned a bill.

Questions they will throw at the end

"What is deprecated that people still write?" create_react_agent from langgraph.prebuilt in favour of create_agent from langchain.agents, where prompt= became system_prompt=. MessageGraph, slated for removal in 2.0, in favour of StateGraph with a messages key. from langgraph.constants import Send in favour of langgraph.types. config_schema= in favour of context_schema= with a Runtime[Ctx] node parameter. checkpoint_during= in favour of durability=. And langgraph-supervisor is no longer actively maintained — the documented replacement is the subagents pattern, where a create_agent has tools that wrap worker agents.

"How do you test a graph?" Three granularities: nodes in isolation (graph.nodes["classify"].invoke(state)), structure and routing with stubbed models, and from the middle via update_state(config, values, as_node=...) then invoke(None, config, interrupt_after=[...]). A fresh graph with a fresh InMemorySaver per test, or threads leak between tests. Model quality belongs in evaluation, not in pytest.

"What breaks when you redeploy?" Latest code applies to all threads, including in-flight ones. Safe: adding, removing or rerouting edges; adding optional or NotRequired state keys. Unsafe: renaming or removing a node while threads are paused at it; renaming a state key, which loses its contents; narrowing a type. The pattern is add-then-remove across two releases, with a thread search on status=interrupted|busy before deleting anything.

"Why not just use create_agent?" Often you should. LangGraph is the low-level orchestration runtime; create_agent is the higher-level agent built on it. You drop to LangGraph when you need control it does not expose: explicit routing, parallel fan-out with reducers, human approval at a specific point, subgraphs, or per-node retry and timeout policies. Saying this plainly is better than pretending the low-level API is always the answer.

"How would you count tokens?" Three options, and the right answer depends on what you already run. The cheapest is the beta v3 event API: graph.stream_events(input, config, version="v3") returns a stream whose messages projection gives one ChatModelStream per LLM call with a .usage field, so you get per-call usage without any backend. The second is LangSmith tracing, which records it for you alongside inputs and outputs. The third is a gateway in front of your providers, which is also where per-team spend limits and key rotation belong. Mention that stream_events is still labelled beta even though the current docs present it as recommended, and that content-block streaming with v3 requires v3 end to end, inner graphs included — a detail that matters if you compose deployed graphs with RemoteGraph.

"Why does interrupt() work without a checkpointer?" Because nothing raises — verified on 1.2.12, a graph with no checkpointer still returns {'__interrupt__': [...]}. It simply cannot be resumed, so the failure appears later as a resume that starts from scratch. Interrupts need a checkpointer and a thread_id; the library does not stop you from forgetting one.

The mistakes at this level are no longer syntax. They are assumptions about the runtime that hold until the day they do not: that a node runs once, that an empty list clears a key, that a checkpoint is cheap, that a redeploy is invisible. Below are the ones that cost real time, the practices ranked by how much they pay back, and a set of recipes you can lift. Verified against LangGraph 1.2.12.

Errors you will actually hit

Returning [] through a merging reducer and expecting the key to clear. This is silent, which makes it expensive. {"docs": []} through Annotated[list, operator.add] concatenates nothing and changes nothing, so your "reset" node does nothing and the list grows forever. The reducer is the only thing that writes the channel, so to bypass it you must say so: return {"docs": Overwrite([])} with from langgraph.types import Overwrite. Symptom: a list that never shrinks and a prompt that grows until the model starts ignoring the top of it.

Two parallel nodes writing one unreduced key. InvalidUpdateError: At key 'k': Can receive only one value per step. The cause is always the same — a key backed by the default LastValue channel received writes from two nodes in one super-step, and there is no defined merge. Before adding a reducer, ask whether both nodes should be writing it; if not, the reducer hides a design error. Note that this often appears only in production, because staging took a branch where only one node ran.

Forgetting setup() on a Postgres checkpointer or store. The resulting missing-table error reads like a permissions problem and sends people to their DBA. Call checkpointer.setup() and store.setup() once on first use, and keep the call in a migration or startup path rather than in request handling.

A thread_id longer than 255 characters. Composed IDs like tenant:user:session:timestamp:... eventually exceed the column and fail at the database. Use a UUID, or hash your composite key and keep the readable version in thread metadata.

Wrapping interrupt() in try/except. interrupt() works by raising GraphInterrupt, so a bare except Exception: swallows the pause and the run continues as though approval was granted. This is the worst failure in this list because it fails open. Never put a broad except around a node that interrupts, and if a node needs error handling, use the node-level error_handler= instead.

Reordering interrupt() calls in a node. Resumes are matched by order, so inserting a new pause above an existing one misroutes the values. Add new interrupts at the end, or in a new node.

Sync nodes with a timeout. ValueError: Node timeouts are only supported for async nodes because sync Python execution cannot be safely cancelled in-process. timeout= requires async def. There is no workaround in-process; convert the node or wrap the blocking call in asyncio.to_thread inside an async node and accept that the thread itself is not cancellable.

Expecting a RetryPolicy to retry a ValueError. The default retry_on deliberately excludes programmer errors: ValueError, TypeError, ArithmeticError, ImportError, LookupError, NameError, SyntaxError, RuntimeError, ReferenceError, StopIteration, StopAsyncIteration and OSError. For requests and httpx errors it retries only on 5xx. If your transport raises a custom transient exception, list it in retry_on yourself.

A cache_policy with no cache on the graph. add_node(..., cache_policy=CachePolicy(ttl=3)) does nothing unless you also pass cache=InMemoryCache() to compile(). No warning, no cache, just the same bill.

INVALID_CHAT_HISTORY after an interrupt. An AIMessage with tool_calls and no matching ToolMessage. Nearly always caused by resuming a paused agent with a fresh HumanMessage instead of None or Command(resume=...). If the history is already dangling, update_state to remove the orphaned tool calls.

Blocking I/O under langgraph dev or the Agent Server. The ASGI layer flags synchronous calls inside async code. --allow-blocking is a local development switch, not a fix, and BG_JOB_ISOLATED_LOOPS=True in a deployment only stops health checks failing. The fix is async clients: httpx.AsyncClient, async psycopg, async model SDK calls, or asyncio.to_thread.

Python 3.10 async surprises. Context does not propagate into asyncio tasks before 3.11, so get_stream_writer() does not work in async nodes (take a writer parameter instead) and you must pass config explicitly into model.ainvoke(..., config). The Agent Server requires 3.11 anyway; standardise there.

Shipping a node rename while threads are paused at it. The latest deployed code applies to all threads, including in-flight ones, so those threads cannot resume. Covered under practices below, because the fix is a habit rather than a patch.

Practices, in order of leverage

1. Set recursion_limit on every invoke. The defaults in 1.x are high — the docs say 1000 from 1.0.6, the 1.2.12 code uses 10007, overridable with LANGGRAPH_DEFAULT_RECURSION_LIMIT. A router that forgets to return END will therefore spend a very large number of model calls before anything stops it. One config key removes the worst possible bill from your risk register. Pair it with a proactive check on config["metadata"]["langgraph_step"] in routers that can loop.

2. Give every irreversible side effect its own node. This single rule neutralises most of the re-run problems: resumption restarts a node from the top, so anything above an interrupt() or above the line that failed happens again. A node that does one thing has the narrowest possible restart window. Derive idempotency keys from state — thread ID plus entity ID — not from anything generated inside the node.

3. Choose durability deliberately, per flow. The default "async" is right for conversations. "exit" is right for re-runnable batch work and is the cheapest. "sync" is right where a lost step means a lost approval, charge or filed ticket. Making this an explicit decision costs one argument and prevents both classes of regret.

4. Put reducers on keys that might ever fan out. Adding Annotated[list, operator.add] to a key costs nothing today. Adding it after six months of production threads means a state migration. When in doubt about a list or dict key that collects contributions, reduce it now.

5. Use runtime.store and context_schema, not globals and config["configurable"]. StateGraph(State, context_schema=Ctx) plus a runtime: Runtime[Ctx] node parameter gives you typed dependencies, runtime.store, and runtime.stream_writer. The payoff is that the same node works locally and under a server that injects its own store. config_schema= is deprecated with removal planned for 2.0.

6. Stream custom progress from slow nodes. Two get_stream_writer() calls in your retrieval node change the product's perceived quality more than most prompt work. Users forgive twenty seconds they can see; they do not forgive twenty seconds of nothing.

7. Keep secrets out of state, always. State is checkpointed and traced, which means a secret in state becomes two durable copies you did not plan for. Use UntrackedValue for things that must live in state but never persist, and prefer the identity returned by @auth.authenticate flowing into run context over per-user tokens carried in state.

8. Treat the rendered diagram as a reviewable artifact. Commit the output of graph.get_graph().draw_mermaid() and regenerate it in CI. Routing changes then appear in the diff, where a reviewer can see them, instead of hiding inside a conditional edge. Pass destinations= on add_node so Command(goto=...) routes show up too.

9. Set per-node policies through set_node_defaults(), then override. builder.set_node_defaults(retry_policy=RetryPolicy(), timeout=TimeoutPolicy(run_timeout=120, idle_timeout=30)) gives the whole graph a floor, with per-node arguments winning where you need something different. Remember these are resolved at compile() time and are not inherited by subgraphs.

10. Pin langgraph and the checkpointer packages together. Minors are non-breaking under semver and deprecations are removed only in majors, but checkpoint serialisation is the one place where a mismatched pair causes grief. Keep langgraph-checkpoint patched in particular — 4.1.1 contained a deserialisation hardening fix.

Practice cards

Card 1 — Predict the step count. Take a graph with a fan-out of three enrichment nodes, a join, and a router. Before running it, write down how many super-steps a single invoke will take and which nodes share each step. Then run with stream_mode="updates" and check. If you were wrong, you are missing something about triggering, and that misunderstanding is behind most concurrency bugs.

Card 2 — Break and clear a reduced key. Add a reset node that returns {"docs": []} on a key reduced by operator.add. Confirm nothing clears. Change it to Overwrite([]) and confirm it does. Five minutes, and you will never lose an afternoon to this.

Card 3 — Double-send an email. Put a print above an interrupt(), run, resume, count the prints. Then move it to its own upstream node and count again. This is the muscle memory that matters most at this level.

Card 4 — Fork a real thread. Take a thread that produced a wrong answer. List get_state_history(config), find the step where routing went wrong, update_state(prior_config, {...}, as_node="router"), then invoke(None, forked_config). Diff the two final states. You now have a production debugging technique that does not involve guessing at prompts.

Card 5 — Make a timeout fire. Write an async node that sleeps longer than run_timeout, give it TimeoutPolicy(run_timeout=2, idle_timeout=1), and inspect the NodeTimeoutError: .node, .elapsed, .kind ("idle" or "run"). Then add RetryPolicy(max_attempts=2) and confirm the timeout is retried and that writes from the abandoned attempt were discarded.

Card 6 — Trip MULTIPLE_SUBGRAPHS. Compile a subgraph with checkpointer=True, call it twice inside one node, read the error, then fix it three different ways: checkpointer=False, omitting the argument, and one named node per call. Explain to yourself which fix is right for a sub-conversation that must remember earlier turns.

Card 7 — Test from the middle. Pick the deepest node in a graph you own. Write a pytest that reaches it with update_state(config, values, as_node=...) and bounds the run with interrupt_after=[...], instead of driving the graph from START. Compare runtimes and token spend.

Card 8 — Measure a checkpoint. Run a thirty-turn conversation against Postgres, then measure the storage the thread consumed. Re-run it with the biggest key under UntrackedValue, and again with durability="exit". You now have numbers rather than instincts for the cost conversation.

Operational recipes

Recipe: a safe graph migration. Before changing node names or state keys, search threads for status=interrupted|busy to find anything paused. Then ship in two releases. Release one adds the new node and routes to it, keeping the old node in place and keeping new state keys NotRequired or optional. Drain or resume the paused threads. Release two removes the old node. Never rename a state key — its contents are lost — and never narrow a type. For business-logic changes that must not switch mid-thread, stamp a flow_version into state when a thread starts and branch on it, so old threads finish the way they began.

Recipe: a resumable approval flow. Compile with a Postgres checkpointer, invoke with durability="sync", and keep the interrupting node free of side effects. Declare the resume shape so a bad payload from your UI is rejected at the boundary:

from pydantic import BaseModel
from langgraph.types import interrupt

class Decision(BaseModel):
    approved: bool
    by: str

def gate(state):
    decision = interrupt({"doc_id": state["doc_id"]}, response_schema=Decision)
    return {"status": "approved" if decision.approved else "rejected"}

Resume with graph.invoke(Command(resume={"approved": True, "by": "aya"}), config). When a step produced several pauses, resume them together with Command(resume={interrupt_id: value, ...}), reading IDs from Interrupt.id.

Recipe: control checkpoint growth. Three levers, cheapest first. Move keys that never need persisting to UntrackedValue. Set TTLs — on the Agent Server, checkpointer.ttl takes strategy: "delete" or "keep_latest" with default_ttl in minutes and a sweep_interval_minutes defaulting to 5, and store.ttl has its own default_ttl plus refresh_on_read, which defaults to true. Only then reach for DeltaChannel, which is beta in 1.2 and stores per-step deltas with a snapshot_frequency=K, forcing a full snapshot after LANGGRAPH_DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT super-steps (default 5000).

{
  "dependencies": ["."],
  "graphs": { "agent": "./app/graph.py:graph" },
  "env": ".env",
  "python_version": "3.12",
  "api_version": "0.15",
  "checkpointer": { "ttl": { "strategy": "keep_latest", "default_ttl": 20160 } }
}

Recipe: sizing the server. N_JOBS_PER_WORKER defaults to 10 concurrent runs per worker and throughput scales roughly linearly with workers, so capacity planning starts there. LANGGRAPH_POSTGRES_POOL_MAX_SIZE defaults to 150 per replica, which means ten replicas can ask for 1500 connections — size Postgres for that or put a pooler in front, because connection exhaustion is the first thing that breaks. BG_JOB_TIMEOUT_SECS defaults to 86400 and BG_JOB_MAX_RETRIES to 3, resuming from the last checkpoint; a sweeper re-queues runs whose heartbeat lapsed. Hosted HTTP connections are capped at one hour, so long runs rejoin with POST /threads/{thread_id}/runs/{run_id}/stream rather than holding a socket open. And do not run a standalone Agent Server on scale-to-zero platforms: a leased run that stops executing is a lost task. Kubernetes with the langgraph-cloud Helm chart is the documented route, which pairs naturally with /student-guides/kubernetes and /student-guides/helm.

Recipe: handle double texting. The queue allows at most one active run per thread, so a second message arriving mid-run needs a policy. enqueue is the default and is right for a chat where every message deserves an answer. reject is right for an API where the client should back off. interrupt is right for a UI where the newest instruction supersedes the last. rollback is right when the in-flight run should be discarded entirely. Pick per use case, not globally, and write the choice down next to the endpoint.

Recipe: a per-node tracing policy. Set LANGSMITH_TRACING=true with LANGSMITH_API_KEY and a LANGSMITH_PROJECT per environment, then narrow what the sensitive nodes emit with trace_policy= on add_node (1.2.10+), config metadata/tags for filtering, and LangSmith anonymizers for fields you must not store. LANGSMITH_TRACING=false is the kill switch, and LANGGRAPH_CLI_NO_ANALYTICS=1 opts out of CLI analytics. If your organisation standardises elsewhere, the Agent Server also supports Datadog via DD_API_KEY — which wraps the process with ddtrace-run and can conflict with OpenTelemetry — and OTel APM via LS_APM_OTEL_ENABLED, with LOG_LEVEL, LOG_JSON and LOG_COLOR for logs. For an open-source tracing backend you host yourself, which matters when conversation content must stay in a specific region, see /student-guides/langfuse.

The mid-level checklist

Before a LangGraph change goes to production, confirm each of these. Every item maps to a failure above, so none of it is ceremony.

• recursion_limit is set explicitly on every invoke that can loop.
• No node that interrupt()s performs an irreversible side effect before the pause, and nothing wraps interrupt() in a broad except.
• Every list or dict key written by more than one node has a reducer, and every reset uses Overwrite.
• A real checkpointer is configured, with setup() called once outside the request path — and not configured in code if this deploys to the Agent Server.
• durability is chosen per flow and the choice is written down.
• thread_id is a UUID or a hash, never a long composed string.
• Async nodes are genuinely async: async HTTP, async DB, async model calls, no blocking call hiding inside.
• timeout= appears only on async def nodes, and cache_policy= only where compile(cache=...) is also set.
• No secret appears in state; UntrackedValue covers anything that must not be checkpointed.
• Store namespaces start with the tenant, and memory writes go through one deliberate extraction node.
• The committed Mermaid diagram was regenerated, and destinations= is set on nodes that use Command(goto=...).
• If a node or key is being renamed or removed, paused threads were found via status=interrupted|busy and the change is split across two releases.
• Deprecated APIs are gone: create_react_agent, MessageGraph, Send from langgraph.constants, config_schema=, checkpoint_during=.
• Tests compile a fresh graph with a fresh InMemorySaver, assert on routing and state transitions, and leave model quality to evaluation — see /student-guides/ragas and /student-guides/promptfoo.

This is part three of three. Beginner taught you the graph. Mid taught you to run one well. This level is about the position you take when a dozen other teams write graphs and you are the person who gets paged when they stop.

The change in question is not "how do I build a better agent". It is: whose Postgres is this, who may read thread 7f3c, what happens to a run that was mid-tool-call when the pod was evicted, what the checkpoint table costs per month, and what breaks when somebody deploys a graph that renames a node while four hundred threads are paused inside it.

Where this picks up

Everything below is verified against LangGraph 1.2.12 (released 21 September 2026), langgraph-cli 0.4.32, and Agent Server (langgraph-api) 0.15.1. Where the published docs and the installed code disagree, I say so, because at this level you will be the one explaining the discrepancy to someone who read the docs.

The architecture you are actually operating

Most teams meet LangGraph as a library and never notice that the deployed product is a distributed system with a specific, knowable shape. You cannot run it as a platform without that shape in your head, because every failure you will debug is a failure of one of four components.

The Agent Server — the component the CLI builds and the thing LangSmith Deployment hosts — is made of API servers, queue workers, PostgreSQL and Redis. Postgres is the system of record: assistants, threads, runs, crons, checkpoints and the long-term store all live there. Redis holds nothing durable. It carries pub/sub for streaming, cancellation signals and run notification. If Redis is wiped you lose in-flight streaming and have to reconnect; if Postgres is wiped you have lost the product.

The run lifecycle is worth tracing once in full, because it explains most incidents. A client calls the API, which writes a pending run row into Postgres and notifies Redis. A worker leases that run, executes the graph, and writes a checkpoint per super-step. Events flow back through Redis to the SSE stream the client is holding open. The queue admits at most one active run per thread, which is why a second request to a busy thread needs a multitask_strategy rather than simply running in parallel.

Three deployment modes exist in the Helm chart and they are not interchangeable. Single host puts the API and the queue in one process and is the self-hosted default; it is fine until the API tier and the execution tier need different scaling curves, which happens the first time one team ships a graph with twenty-minute runs. Split API and queue (queue.enabled: true) lets you scale a thin, latency-sensitive API tier separately from fat, long-running workers. Distributed runtime separates orchestration from execution for high concurrency; reach for it when you have measured the need, not before.

Above that sit the hosting choices. LangSmith Cloud offers serverless and dedicated deployment types under the current usage-based pricing; organisations still on the legacy dev/prod types keep them only until 1 October 2026, which is a migration you should have dated. Self-hosted LangSmith splits a control plane from a data plane and is an Enterprise add-on. The hybrid, or listener, shape keeps execution in your cluster while the LangSmith control plane manages deployments. And standalone Agent Server runs entirely on your infrastructure with no control plane, which is the shape most Gulf and Egyptian teams with a data-residency obligation end up choosing, because it keeps thread contents inside a region you control. For standalone, use Kubernetes with the langgraph-cloud Helm chart. Docker and Compose are development tools here.

A standalone server needs REDIS_URI, DATABASE_URI, LANGSMITH_API_KEY and LANGGRAPH_CLOUD_LICENSE_KEY, with LANGSMITH_ENDPOINT if you point at self-hosted LangSmith. Two rules about sharing infrastructure: deployments may share a Redis instance on different DB numbers and a Postgres instance with different databases, but never the same DB number or the same database. The second rule is the one people break, usually by copying a connection string between a staging and a production values file.

Which component breaks first

Capacity planning for LangGraph is unusual because the bottleneck is almost never CPU. Runs spend their lives waiting on model APIs. So the limits you hit are concurrency limits and connection limits, in a predictable order.

The first knob is N_JOBS_PER_WORKER, the number of concurrent runs a worker will execute, default 10. Throughput scales roughly linearly with workers, which is the happy part. The unhappy part arrives at the database: LANGGRAPH_POSTGRES_POOL_MAX_SIZE defaults to 150 per replica, so ten replicas can open fifteen hundred connections. Managed Postgres instances do not have fifteen hundred connections. This is the most common first wall, and its symptom is not a LangGraph error at all — it is connection exhaustion that takes down anything else sharing the instance.

So the sizing conversation goes: pick your target concurrent runs, divide by N_JOBS_PER_WORKER to get replicas, multiply replicas by the pool size, and compare that number against your Postgres max_connections with headroom for migrations, backups and your own admin sessions. If the arithmetic does not close, lower the pool size per replica before adding a connection pooler, because the pooler adds a component you then have to operate.

Long runs are the second wall. BG_JOB_TIMEOUT_SECS defaults to 86,400 — a full day — which means a wedged run will sit there for a day unless something else kills it. Separately, Cloud HTTP connections are capped at one hour, so any client streaming a run longer than that will be disconnected regardless of the job timeout. The fix is not a longer connection; it is teaching clients to rejoin with POST /threads/{thread_id}/runs/{run_id}/stream. Any SDK wrapper you give other teams should do that rejoin automatically, because they will not.

On failure, BG_JOB_MAX_RETRIES (default 3) resumes the run from its last checkpoint rather than from the beginning — which is the whole point of durable execution, and also the reason non-idempotent side effects become visible at this level and not earlier. On a hard crash, a sweeper runs every two minutes and re-queues runs whose heartbeat has lapsed. A SIGINT stops intake and drains, with BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS (default 180, maximum 3600) bounding how long that takes. Set that grace period longer than your p99 super-step, or every deploy will kill work mid-step and rely on the retry path.

Inside the library, the lever is durability. The default is "async": the checkpoint persists while the next step runs, which costs almost nothing and risks losing the most recent step on a hard crash. "sync" persists before the next step starts and is the right choice for anything with external side effects you cannot replay. "exit" persists only when the run exits, which is the fastest and gives you no mid-run crash recovery at all. A platform position worth writing down: "sync" for graphs that move money, send messages or call partner APIs, "async" as the default, "exit" only for short batch graphs where a rerun from scratch is cheap.

Fault tolerance as a design surface

Version 1.2 turned fault tolerance from one retry decorator into a surface you can actually design against, and most of it is Python-only. Treating it as a platform default rather than per-graph decoration is one of the highest-leverage things you own.

from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.types import RetryPolicy, TimeoutPolicy
from langgraph.errors import NodeError

def on_error(state: MessagesState, error: NodeError) -> dict:
    # Runs after retries are exhausted. Return a state update or a Command.
    return {"messages": [{"role": "ai", "content": f"step failed: {type(error.__cause__).__name__}"}]}

async def call_model(state: MessagesState) -> dict:
    ...

builder = StateGraph(MessagesState)
builder.set_node_defaults(
    retry_policy=RetryPolicy(max_attempts=3),
    error_handler=on_error,
)
builder.add_node(
    "call_model",
    call_model,
    timeout=TimeoutPolicy(run_timeout=120, idle_timeout=30),
)
builder.add_edge(START, "call_model")
builder.add_edge("call_model", END)
graph = builder.compile()

RetryPolicy's defaults are max_attempts=3, initial_interval=0.5, backoff_factor=2.0, max_interval=128.0, jitter=True. Its default retry_on is the part people misread: it retries most exceptions but not ValueError, TypeError, ArithmeticError, ImportError, LookupError, NameError, SyntaxError, RuntimeError, ReferenceError, StopIteration, StopAsyncIteration or OSError, and for requests/httpx errors it retries only on 5xx. That list is sensible — retrying a TypeError just burns tokens on the same bug — but it means a flaky dependency that raises OSError will not be retried unless you say so explicitly.

Timeouts have a hard constraint you should communicate before anyone designs around them: they work on async nodes only. A sync node with a timeout raises ValueError: Node timeouts are only supported for async nodes because sync Python execution cannot be safely cancelled in-process. Node 'a' is sync. This is not a bug to work around; synchronous Python cannot be cancelled safely in-process. The practical consequence is that "every model call must be cancellable" becomes "every model call must be async def", which is a rule to put in your template rather than a review comment you repeat forever.

TimeoutPolicy distinguishes two clocks. run_timeout bounds total node duration; idle_timeout bounds the gap since the last sign of life. NodeTimeoutError carries .node, .elapsed, .kind ("idle" or "run"), .idle_timeout and .run_timeout — log all five and your timeout incidents become self-diagnosing. Writes from a timed-out attempt are discarded, which is what makes timeouts safe to retry; NodeTimeoutError is itself retryable. An async-generator node can yield {} as a heartbeat to reset the idle clock, which is how you keep a legitimately slow streaming node from being killed.

Four rules about defaults, all of which have bitten someone:

1. Per-node arguments override set_node_defaults.
2. Defaults resolve at compile() time and are not inherited by subgraphs. Every subgraph needs its own set_node_defaults call.
3. error_handler and cache_policy defaults do not apply to handler nodes, so a handler cannot accidentally handle itself.
4. There is one handler per node, and a failing handler propagates. Handlers must be boringly safe code.

And one rule that matters for human-in-the-loop graphs: interrupt() bypasses error handlers. It works by raising GraphInterrupt, so an error handler that treats every exception as a failure would otherwise swallow your pauses. This is the same reason the docs forbid wrapping interrupt() in try/except.

Graceful shutdown is the piece that makes rolling deploys safe:

import signal
from langgraph.runtime import RunControl
from langgraph.errors import GraphDrained

control = RunControl()
signal.signal(signal.SIGTERM, lambda *_: control.request_drain("sigterm"))

try:
    result = graph.invoke(payload, config, control=control)
except GraphDrained as drained:
    # The checkpoint is saved. Resume later on the same thread_id.
    log.info("drained: %s", drained)

control.request_drain(reason) can be called from any thread. The run stops after the current super-step, the checkpoint is saved, and GraphDrained(reason) is raised. You resume with graph.invoke(None, config) on the same thread. control.drain_requested lets you distinguish a drain from a normal finish that happened on the same tick, which matters when you are deciding whether to re-enqueue.

Checkpoint storage and the cost of remembering

A checkpointer writes a snapshot of state per super-step. That sentence is unremarkable until you multiply it: a graph whose state holds a growing message list, run over a long thread, stores the whole list again at every step. Checkpoint tables are the fastest-growing thing in most LangGraph deployments and nobody owns them by default.

You have four levers and they compose.

Durability decides how often you pay the write. "exit" writes once per run. For a batch graph that fans out over documents, this is often a tenfold reduction in write volume for an acceptable loss of mid-run recovery.

DeltaChannel (beta, 1.2+) attacks the size rather than the count. Instead of storing the full value each step, it stores per-step deltas and takes a full snapshot every snapshot_frequency steps:

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.channels import DeltaChannel

def batch_reducer(current: list, writes: list) -> list:
    out = list(current)
    for write in writes:
        out.extend(write)
    return out

class State(TypedDict):
    messages: Annotated[list, DeltaChannel(batch_reducer, snapshot_frequency=5)]

Note the signature difference: the reducer receives (current, writes_sequence), not (current, update). The runtime also forces a snapshot after LANGGRAPH_DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT super-steps, default 5000, so a thread cannot accumulate an unbounded delta chain. Rollback has caveats documented with Pregel; read them before putting this on a graph that uses time travel heavily. It is beta, which in LangGraph's labelling means production-safe but subject to change — acceptable for an internal platform where you control the upgrade, less so for a library other companies consume.

TTLs stop storage growing forever. In langgraph.json, checkpointer.ttl takes a strategy of "delete" or "keep_latest", a default_ttl in minutes, a sweep_interval_minutes (default 5) and a sweep_limit (default 10,000 on server 0.12+). store.ttl has its own refresh_on_read (default true), default_ttl in minutes and sweep_interval_minutes.

{
  "dependencies": ["."],
  "graphs": { "agent": "./src/agent.py:graph" },
  "env": ".env",
  "api_version": "0.15",
  "checkpointer": {
    "ttl": { "strategy": "keep_latest", "default_ttl": 20160, "sweep_interval_minutes": 5 }
  },
  "store": {
    "ttl": { "refresh_on_read": true, "default_ttl": 129600 }
  }
}

"keep_latest" is usually the right strategy for conversational products: you keep the thread's current state so a user can resume, and you drop the history that made time travel possible. "delete" is right for machine-to-machine graphs with no human to come back. The unit being minutes is a genuine foot-gun — 20160 above is fourteen days, and somebody on your team will read it as seconds.

Two more operational notes. UntrackedValue is the channel type for state that is never checkpointed, which is the correct home for a large intermediate blob you do not want written forty times. And deferred deletion via LS_CHECKPOINT_DELETE='{"enabled":true,...}' moves delete I/O off the request path, which matters once sweeps are large enough to contend with live traffic. Server 0.16 RC adds GET /threads/{id}/storage reporting checkpoint bytes, which is the metric to graph per tenant once you have it.

The trust model, secrets and the supply chain

Here is the sentence that should shape your whole security posture: self-hosted Agent Server has no default authentication. LangSmith-hosted deployments require a LangSmith API key in the x-api-key header, so people who start on Cloud carry an assumption that evaporates the moment they move in-house. If you stand up a standalone server and expose it, anyone who can reach the port can read every thread.

Authentication and authorisation are code you write, registered through langgraph.json:

from langgraph_sdk import Auth

auth = Auth()

@auth.authenticate
async def authenticate(authorization: str | None) -> Auth.types.MinimalUserDict:
    user = await verify_bearer(authorization)
    if user is None:
        raise Auth.exceptions.HTTPException(status_code=401, detail="Invalid token")
    return {"identity": user.id, "permissions": user.scopes}

@auth.on.threads.create
async def own_new_threads(
    ctx: Auth.types.AuthContext,
    value: Auth.types.on.threads.create.value,
):
    value.setdefault("metadata", {})["owner"] = ctx.user.identity
    return {"owner": ctx.user.identity}   # also used as a read/search filter

The returned dict does double duty: it stamps ownership on writes and acts as a filter applied to reads and searches. That is the mechanism that makes one deployment safe for many users, and it is why a missing handler is not a cosmetic gap — it is an unfiltered list endpoint.

Handler precedence runs from specific to general: an action handler (@auth.on.threads.create) beats a resource handler (@auth.on.threads), which beats the global @auth.on. The resources are threads (create, read, update, delete, search, create_run), assistants (create, read, update, delete, search), crons (the same five) and store (@auth.on.store). A platform pattern that holds up in review: write a deny-by-default global @auth.on, then open specific actions. The opposite order leaves holes you discover by audit.

Three more settings carry real risk. disable_studio_auth controls Studio access and should be false anywhere real data lives. CORS defaults to * via CORS_ALLOW_ORIGINS, so tighten it on day one. And auth.allow_langsmith_api_keys: true accepts LangSmith keys alongside your own scheme, which is convenient during migration and a second front door afterwards.

Serialization is the supply-chain surface. The default serializer is JsonPlusSerializer (ormsgpack plus JSON). JsonPlusSerializer(pickle_fallback=True) will happily round-trip pandas frames and other unsupported types, and it is a security trade-off you should refuse by default: pickle deserialisation of attacker-influenced bytes is code execution. If a team insists, make them justify why the object cannot be reduced to JSON. On the server, serde.allowed_json_modules limits which modules may be deserialised; set it. And keep langgraph-checkpoint patched — 4.1.1 restricted lc:2 envelope revival to the default constructor as a deserialisation hardening fix, which is exactly the class of patch you do not want to be three minors behind on.

Encryption at rest is a one-liner and worth doing even when the database is already encrypted, because it changes who can read a checkpoint from "anyone with a database dump" to "anyone with the key":

from langgraph.checkpoint.serde.encrypted import EncryptedSerializer
from langgraph.checkpoint.postgres import PostgresSaver

serde = EncryptedSerializer.from_pycryptodome_aes()   # reads LANGGRAPH_AES_KEY

with PostgresSaver.from_conn_string(DB_URI, serde=serde) as checkpointer:
    checkpointer.setup()
    graph = builder.compile(checkpointer=checkpointer)

On LangSmith Deployment, simply setting LANGGRAPH_AES_KEY enables it. A custom CipherProtocol is supported if you must route through a KMS or a HashiCorp Vault transit key — see /student-guides/vault for the key-management side of that.

Secrets discipline has one absolute rule: never put secrets in graph state. State is checkpointed and traced, so a token in state becomes a token in Postgres and a token in LangSmith, retained for as long as your TTLs allow. Use .env only locally; in deployments use deployment secrets or Kubernetes secrets. For per-user credentials, the right channel is the value returned from @auth.authenticate, which flows into run context — delegated credentials without baking a per-user token into a checkpoint. Webhook header templates can only read environment variables prefixed LG_WEBHOOK_, which is a deliberate containment boundary rather than an inconvenience.

Multi-tenancy without a deployment per tenant

The instinct when a second team asks for a graph is to give them a second deployment. Sometimes that is right — different compliance regimes, wildly different scaling curves, or a hard blast-radius requirement. Usually it is an expensive way to avoid writing thirty lines of authorisation code, because each deployment brings its own Postgres database, Redis DB number, upgrade schedule and on-call surface.

Isolation inside one deployment has three layers. Short-term state is isolated by thread_id. Long-term memory is isolated by store namespace, and namespaces are tuples, so (tenant_id, user_id, "memories") gives you a hierarchy you can filter and sweep. Access is enforced by the auth handlers above — including @auth.on.store, which people forget, leaving cross-thread memory readable when threads are not.

Configuration per tenant is what assistants are for. An assistant is a versioned configuration of a deployed graph: the graph ID plus config and context. One graph, one image, one deployment, and a different model, prompt or tool allowlist per tenant, each version addressable so you can roll one tenant forward without touching the others. That is a much better story than a branch per customer.

The remaining tenancy question is what happens when a tenant's user sends a second message while the first run is still going. Because the queue admits one active run per thread, you must pick a multitask_strategy per run: enqueue (default — run them in order), reject (refuse the new one), interrupt (stop the current run and start the new one) and rollback (discard the current run's work and start the new one). For a chat product, interrupt usually matches what a user means when they type again. For anything with side effects, enqueue or reject are the only defensible choices, because rollback throws away work that may already have touched the outside world. This is an Agent Server feature, not part of the OSS library: if a team embeds the library in their own service, they own this behaviour themselves and will almost certainly get it wrong on the first attempt.

One hard constraint to put in writing: separate deployments must not share a Postgres database or a Redis DB number. When you do split tenants across deployments, make the database and DB-number allocation part of the provisioning template rather than something a human types.

Upgrades and migrations against live threads

This is the section that distinguishes a platform owner from a careful developer, because it is about a property no local test reproduces: LangGraph applies the latest deployed code to all threads, including in-flight ones. There is no version pinning per thread. A thread paused at an interrupt for three days will resume into whatever code you deployed yesterday.

Safe changes, per the backward-compatibility documentation: adding, removing or rerouting edges; adding state keys as NotRequired or optional. Unsafe changes: renaming or removing a node while threads are paused at it or about to enter it; renaming state keys, which silently loses their contents; and narrowing types, which turns old checkpoints into validation errors.

The operational pattern that follows is add-then-remove, with a drain in the middle. To replace node review with review_v2: deploy both, route new threads to review_v2, let the threads paused at review finish or be resumed, confirm none remain, then remove review. Finding them is a thread search on status=interrupted|busy, and that query belongs in your release checklist as a gate, not a suggestion.

For business-logic changes rather than structural ones, stamp a flow_version into state at thread start and branch on it. It costs one key and it converts "we cannot change the refund flow because of in-flight threads" into "old threads run the old branch".

The Functional API deserves its own warning. An @entrypoint compiles to a single node that replays from the start on resume, using cached task results. So you must never add, remove or reorder @task or interrupt() calls before the resume point, and code outside tasks must be deterministic. A conditional that reads the clock, a loop over a set, a newly inserted @task at the top of the function — each one shifts the replay alignment and corrupts resumption for every paused thread. If a team wants the Functional API's ergonomics, make sure they understand that its deployment constraints are stricter than the Graph API's, not looser.

Version pinning is the other half. Pin langgraph and the checkpointer packages together, because they share a serialisation contract. On the server, the release streams are latest (daily dev builds), rc (every three weeks) and stable (the default for new deployments, with revisions automatically moving to the newest stable). Automatic movement is convenient and also means an upgrade you did not schedule. Pin it with api_version in langgraph.json — "0.15" pins the minor — or with base_image, and move the pin deliberately. The library's own policy helps you plan: majors are six to twelve months apart, minors every one to two months, patches often weekly, deprecated features keep working for at least one minor and are removed only in a major, and Python requirements change only in majors.

Observability, trace budgets and what to alarm on

Tracing an agent is not optional — you cannot debug a non-deterministic multi-step process from logs — but at platform scale it is a cost centre and a data-governance question at once.

The mechanics are familiar: LANGSMITH_TRACING=true plus LANGSMITH_API_KEY, with LANGSMITH_PROJECT selecting a project. Per-run metadata and tags in the config are what make traces searchable six weeks later; mandate a small set — tenant, assistant, flow version, release — in your template so that every team's traces are queryable the same way. Node-level control arrived in 1.2.10 with trace_policy= on add_node, which is how you keep a chatty retrieval loop from dominating your trace volume. LangSmith anonymizers strip sensitive fields before anything leaves your process, and that is the control to point at when a compliance reviewer asks whether customer messages leave the region. LANGSMITH_TRACING=false turns the whole thing off, and LANGGRAPH_CLI_NO_ANALYTICS=1 opts out of CLI analytics.

Inside a node, config["metadata"] carries langgraph_step, langgraph_node, langgraph_triggers, langgraph_path and langgraph_checkpoint_ns. langgraph_step is the one with operational value: reading it lets a node notice it is on step 400 of a loop and exit deliberately, instead of letting the run die on the recursion limit.

Which brings us to the recursion limit, where you must know something the documentation does not say. The docs state the default became 1000 in 1.0.6. In the installed 1.2.12 the effective default is 10,007 super-steps, from DEFAULT_RECURSION_LIMIT = int(getenv("LANGGRAPH_DEFAULT_RECURSION_LIMIT", "10007")). The odd number is a sentinel introduced by a 1.1.4 fix to avoid a default-collision. Ten thousand super-steps of an agent loop is an enormous token bill arriving before any error does. The platform rule is therefore: always set recursion_limit explicitly in the config for any agent loop, and set LANGGRAPH_DEFAULT_RECURSION_LIMIT to something sane at the deployment level as a backstop. Do not teach 25; that was the pre-1.0.6 default and repeating it will mislead people.

On the server side, the Agent Server exposes Datadog via DD_API_KEY (it wraps the process with ddtrace-run, which can conflict with OpenTelemetry), OTel APM via LS_APM_OTEL_ENABLED, and logging via LOG_LEVEL, LOG_JSON and LOG_COLOR. Turn on LOG_JSON before you need it. The /ok health endpoint reports per-dependency services from 0.16, which makes a "which dependency is down" check possible without guessing. The library also emits graph lifecycle callback handlers from 1.1.7, which is the hook for pushing custom metrics into /student-guides/prometheus or an /student-guides/opentelemetry pipeline.

A starting alarm set, in order of how often it will save you: Postgres connection utilisation against the pool arithmetic; pending-run queue depth and age; runs retried by the sweeper; interrupted-thread count and age, because a growing pile means a human queue nobody is working; checkpoint table growth per day; NodeTimeoutError rate by node; and token spend per tenant. For the last one, token accounting comes from the v3 messages usage projection or from LangSmith; pair it with /student-guides/langfuse if you want per-tenant spend attribution outside LangSmith, and with /student-guides/ragas when the question shifts from cost to answer quality.

Streaming at the edge: v3 and the versions question

Streaming deserves a section at this level because it is where version confusion costs real debugging hours, and because you will be the one deciding what your platform supports.

Three output versions coexist. invoke and stream still default to version="v1" — verified in code: Pregel.invoke(..., version: Literal['v1','v2'] = 'v1'). v2 is opt-in and returns a typed GraphOutput with .value and .interrupts, coercing Pydantic or dataclass state back to its type; its streams yield {"type", "ns", "data"} parts. v3 is not a value of that parameter at all: it exists only on the separate stream_events() / astream_events() method.

run = graph.stream_events(payload, config, version="v3")
for chunk in run.messages:          # one ChatModelStream per LLM call
    print(chunk.text, end="")
print(run.output, run.interrupts)

stream_events returns a GraphRunStream (async: AsyncGraphRunStream) with built-in projections run.values, run.messages, run.lifecycle and run.subgraphs, plus run.output, run.interrupted and run.interrupts. The messages projection gives one ChatModelStream per LLM call exposing .text, .reasoning, .tool_calls, .usage and .output — .usage is where your per-run token accounting comes from. Opt-in transformers from langgraph.stream (UpdatesTransformer, CustomTransformer, CheckpointsTransformer, TasksTransformer, DebugTransformer, and ToolCallTransformer in prebuilt) register via compile(transformers=[...]) or at the call site, and custom StreamTransformer subclasses declare their required_stream_modes.

Two traps. Projections are single-consumer: reading run.messages and run.values in the same pass needs .tee(n) / .atee(n) or run.interleave("messages", "values"). And content-block streaming requires v3 end to end, including inner graphs — one subgraph left on an older path and the blocks stop arriving, with no error to tell you why.

The platform decision: v3 is labelled beta, and the current interrupts and graph-API documentation pages already write their examples with it and call it recommended. Beta in LangGraph's labelling means production-safe but subject to change. My position for a platform is to support v3 behind your own thin client wrapper, so that if the shape moves you change one file rather than every team's frontend. Also note the interrupt-reading difference across versions, because it generates support tickets: result["__interrupt__"] in v1, result.interrupts in v2, and stream.interrupts / stream.interrupted in v3. Dict-style access on a v2 GraphOutput is deprecated since 1.1 with removal planned for 3.0.

Incident playbooks

These are the five pages you want in your runbook before you need them. Each starts from what the on-call person actually sees.

Runs are queued and nothing executes. Check worker liveness and the Redis connection first, because the queue notification path runs through Redis. Then check Postgres connection availability — if workers cannot get a connection they cannot lease. Remember the sweeper re-queues lapsed-heartbeat runs every two minutes, so a steadily growing pending count with no leases points at the workers, while a sawtooth points at workers that lease and then die.

One thread is stuck. Fetch graph.get_state(config) and read next: an empty tuple means finished, a populated one tells you which node is pending. Then tasks on the snapshot gives you PregelTask entries with error and interrupts. If there is an interrupt, this is not a stuck thread, it is a thread waiting on a human — route it to whoever owns that queue. If there is an error, get_state_history(config) shows you the step before it, and metadata.source ("input", "loop" or "update") tells you whether the last change came from a client, the loop, or somebody's manual update_state.

A node loops until the limit. You will see GraphRecursionError: Recursion limit of N reached without hitting a stop condition. The cause is a router that never returns END, or a genuinely long graph. The fix is the router, not the limit — but set an explicit limit anyway so the next occurrence costs you minutes of tokens instead of hours. Add a langgraph_step guard in the loop node for graphs where looping is expected.

Parallel writes collide. InvalidUpdateError: At key 'k': Can receive only one value per step. Use an Annotated key to handle multiple values. Two nodes in the same super-step wrote a key with no reducer, almost always after someone added a fan-out or a Send. Add Annotated[list, operator.add] or a purpose-built reducer. The related trap: returning an empty list through a merging reducer does not clear the key — you need Overwrite(value) from langgraph.types to bypass the reducer.

An agent thread will not accept new input. INVALID_CHAT_HISTORY means an AIMessage with tool_calls has no matching ToolMessage, which typically happens when someone sends a fresh HumanMessage to a thread that was interrupted or hit an unhandled tool error. Resume with None or Command(resume=...), add the matching ToolMessages, or use update_state to remove the dangling tool calls. Teaching client teams to resume rather than re-send prevents most of these.

Two more you will see constantly in the first month of a deployment. Blocking I/O inside async code is flagged by the ASGI server; the fix is async clients (httpx.AsyncClient, psycopg async, async model SDK calls) or asyncio.to_thread. langgraph dev --allow-blocking is for local development only, and BG_JOB_ISOLATED_LOOPS=True in deployments stops health checks failing without removing the underlying problem — treat it as a symptom suppressor. And missing tables: forgetting checkpointer.setup() or store.setup() on first use. While you are there, cap thread_id length: values over 255 characters cause a database error, so hash or UUID anything derived from a customer identifier.

Where LangGraph stops

A platform owner's most valuable skill is declining. LangGraph is deliberately low-level: "a low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents", inspired by Pregel and Apache Beam, with an API that resembles NetworkX. It does not abstract prompts or agent architecture. That is a strength and a boundary.

If a team's problem is a DAG of batch data transformations on a schedule, they want a workflow orchestrator, not an agent runtime. /student-guides/airflow, /student-guides/prefect and /student-guides/dagster give you backfills, data-aware scheduling and lineage that LangGraph has no opinion about. Checkpoint-per-super-step is the wrong storage model for a nightly job over ten million rows.

If the problem is serving a model under latency pressure, that is an inference server's job — /student-guides/vllm or /student-guides/kserve — and LangGraph calls it, rather than replacing it.

If the problem is a single prompt with tools and no durable state, create_agent from /student-guides/langchain is enough, and a plain request handler in /student-guides/fastapi is enough on top of it. Do not make a team adopt threads, checkpointers and a Postgres dependency to answer one question synchronously.

If the problem is evaluation and quality, LangGraph is the thing under test, not the test harness. That is /student-guides/ragas and /student-guides/langfuse territory.

And if a team wants a different agent framework entirely, the Agent Server can still host it: other frameworks — the Claude Agent SDK, Strands, Google ADK — can be deployed on it via the Functional API wrapper. That is a genuinely useful platform move, because it lets you offer one deployment story, one auth model and one observability pipeline across frameworks you did not choose.

The honest cases for using the library without the server are also worth naming. You can embed LangGraph in your own FastAPI or worker service with PostgresSaver and skip the Agent Server entirely. You then own queuing, per-thread concurrency, streaming and auth — four things the server already does correctly. Choose it when you have an existing platform those concerns already live in, not to avoid learning the server.

Running it as a platform for other teams

Everything above becomes a product when you package it. Five pieces, in the order they pay off.

A template, not a tutorial. langgraph new path/to/app --template new-langgraph-project-python gets a team started; your template should go further and bake in the decisions you do not want relitigated: async nodes throughout, set_node_defaults with retry and timeout policies, an explicit recursion_limit, mandated metadata keys, a flow_version key in state, api_version pinned in langgraph.json, TTLs configured, and an auth.py with deny-by-default. A team that starts from that template is compliant by accident.

A registration contract. For deployed graphs, a compiled graph variable is recommended because it is loaded once; a factory make_graph(config) runs per request and adds overhead. And the rule that surprises everyone: do not configure a checkpointer or store in code for Agent Server deployments. The server injects them. A graph that hard-codes InMemorySaver will deploy and then quietly lose state.

Guardrails in CI. Lint for the things that only hurt in production: a sync node with a timeout, pickle_fallback=True, secrets assigned into state keys, a missing recursion_limit, deprecated imports from langgraph.constants, and MessageGraph. Compile every graph in CI — compile() validates structure and will catch orphan nodes, a missing entrypoint (ValueError: Graph must have an entrypoint: add at least one edge from START to another node) and edges to unknown nodes (Found edge ending at unknown node) before a deploy does.

A test convention. The official guidance is to compile a fresh graph per test with InMemorySaver, test a node in isolation via compiled.nodes["name"].invoke(state), and do partial execution with update_state(config, values, as_node=...) followed by invoke(..., interrupt_after=[...]). Publishing that as a shared pytest fixture package is an afternoon's work and removes the single most common reason teams ship untested graphs.

A deployment pipeline. langgraph deploy is beta but usable, and its subcommands are what make it operable: deploy list [--name-contains], deploy delete [--force], deploy logs [-f] [--type deploy|build] [--level] [--start-time/--end-time ISO8601] [--limit 100] [--revision-id] and deploy revisions list [--limit 10]. Useful flags: --deployment-type serverless|dedicated, --push-to <registry repo> which is required for self-hosted and listener workspaces, --image for a prebuilt image that must be linux/amd64, -t/--tag (default latest), --remote/--no-remote for remote builds when there is no Docker, and --listener-id / --k8s-namespace for listener deployments. LANGGRAPH_HOST_URL=https://eu.api.host.langchain.com selects the EU region; for a self-hosted control plane set LANGSMITH_ENDPOINT and the CLI derives https://<host>/api-host — and make sure that endpoint has no trailing slash, which causes auth errors. Avoid --tag latest in anything you intend to roll back.

For Kubernetes, the langgraph-cloud chart from langchain-ai/helm is the supported path; manage it the way you manage everything else, through /student-guides/helm and /student-guides/argo-cd, so that a revision is a commit. A note for standalone operators: the server needs egress to https://beacon.langchain.com unless air-gapped, and LANGGRAPH_CLOUD_LICENSE_KEY is validated once at startup — a blocked egress rule shows up as a server that will not boot, which is a fine thing to know at 2am and a terrible thing to discover then.

Finally, publish the boundaries: which deployment a team lands on, what their TTL is, who answers their interrupted-thread queue, and what you will not host.

The review checklist

Use this on pull requests and design documents. It is ordered so that the first failure usually matters most.

Correctness and durability. Every node returns a dict of state keys or a Command, on every code path. Every state key written by parallel nodes has a reducer. Clearing a reduced key uses Overwrite. recursion_limit is set explicitly. durability is chosen deliberately, with "sync" for anything with external side effects. Side effects before an interrupt() are idempotent, because the node reruns from the start. No try/except wraps an interrupt(). Interrupt order within a node is fixed.

Resilience. Nodes that call the network are async def. TimeoutPolicy has both run_timeout and idle_timeout. set_node_defaults is present, and repeated in every subgraph because defaults are not inherited. error_handler functions cannot themselves fail. SIGTERM is wired to control.request_drain.

Security. @auth.authenticate exists and a deny-by-default @auth.on precedes any permissive handler. @auth.on.store is covered, not just threads. No secrets in state. No pickle_fallback. serde.allowed_json_modules is set. CORS is not *. disable_studio_auth is false. LANGGRAPH_AES_KEY is set where checkpoints hold personal data.

Cost and storage. checkpointer.ttl and store.ttl are configured, with the units read as minutes. Large intermediates use UntrackedValue. Long threads consider DeltaChannel. Token usage is attributed per tenant.

Deployability. The graph is registered as a compiled variable, not a factory, unless there is a reason. No checkpointer or store configured in code for an Agent Server deployment. api_version is pinned. The image is linux/amd64 if passed with --image. Metadata and tags follow the platform convention.

Migration safety. No node renamed or removed while threads may be paused at it. No state key renamed. No type narrowed. New keys are NotRequired. A flow_version exists for logic changes. For Functional API code, no @task or interrupt() added, removed or reordered before a possible resume point. A thread search for status=interrupted|busy was run and is clean.

The complete picture

Put the three levels together and the shape is this. The library gives you a Pregel-style runtime: nodes are functions returning partial state updates, channels and reducers decide how concurrent writes merge, a super-step is one tick in which everything triggered runs in parallel and writes land together, and a checkpointer turns that loop into something durable, inspectable and interruptible. That is the whole conceptual core, and it is small.

The deployment gives you the operational layer around that core: an API tier, queue workers that admit one run per thread, Postgres as the record and Redis as the nerve. Assistants version configuration. Auth handlers stamp ownership and filter reads. TTLs and delta channels keep the record from becoming a bill.

What you own as a platform is the join between the two, and it is mostly made of defaults. The recursion limit nobody sets. The durability mode nobody chose. The sync node nobody can cancel. The missing reducer that only breaks when a fan-out is added. The auth handler nobody wrote because Cloud provided one. The TTL nobody configured until the database doubled. Each is a one-line fix in a template and a multi-day incident in production, and deciding which of those two it will be is the actual job.

The regional note worth making: if you work under a data-residency obligation in the Gulf or Egypt, the standalone Agent Server with your own Postgres in your own region, plus EncryptedSerializer, LangSmith anonymizers or LANGSMITH_TRACING=false, is the configuration that lets you say precisely where thread contents live. That answer is much easier to give if you chose it at the start than if you retrofit it after a year of checkpoints.

Where the series leaves you

You can now design a LangGraph deployment and defend each choice: which mode, how many workers, what the connection arithmetic allows, what the storage will cost, who may read a thread, what happens on SIGTERM, and what breaks on upgrade. You can run an incident from a symptom to a StateSnapshot to a cause. You can say no to a team whose problem is a DAG, and yes with conditions to a team whose problem is an agent.

What remains is judgement you only get from operating it. Run a game day. Set the alarms before you need them. Write the boundaries down. And keep the fact sheet habit: check the installed code against the documentation when a number matters, because the recursion-limit discrepancy in this guide is the kind of thing that only shows up when somebody looks.

From here, the natural next steps in this catalogue are /student-guides/langsmith for the tracing and evaluation side, /student-guides/langfuse if you want an open-source observability path, and /student-guides/kubernetes for the cluster the Helm chart lands on.

Sources

• LangGraph overview
• Graph API
• Pregel runtime
• Persistence
• Checkpointers
• Stores
• Durable execution
• Fault tolerance
• Interrupts
• Time travel
• Subgraphs
• Event streaming
• Backward compatibility
• Observability
• Testing graphs
• Application structure
• Common errors
• LangGraph v1 release notes
• Release policy
• Agent Server
• Custom authentication
• Configure TTL
• Double texting
• Environment variables
• Scalability and resilience
• Deploy a standalone server
• Data storage and privacy
• LangGraph CLI
• langgraph-cloud Helm chart
• LangGraph releases

Senior LangGraph interviews are rarely about the API. The interviewer assumes you can build a graph, and spends the hour finding out whether you have operated one: whether you know what the deployment is made of, what you would measure, how you would recover a thread, and how you would argue a cost or residency decision to someone who does not care about Pregel.

What follows is the shape of those conversations at LangGraph 1.2.12, with the reasoning a strong answer carries and the gaps a weak one leaves.

How to use this

Each prompt below has three parts: what the interviewer is really probing, the answer structure, and the thing that separates a senior answer from a competent mid-level one. Read the probe first. Most candidates lose points not by being wrong but by answering a different question — giving a code answer to an operations prompt, or a tooling answer to a trade-off prompt.

System design: a multi-team agent platform

Prompt. "Five product teams want to ship agents. Design the platform. You own it."

What they are probing. Whether you know the Agent Server's topology, and whether you default to one deployment per team because authorisation is hard.

The answer. Start with the components, because every later decision references them: API servers, queue workers, PostgreSQL as the system of record for assistants, threads, runs, crons, checkpoints and the store, and Redis for pub/sub, cancellation and stream signalling only — nothing durable. Then name the mode: single host is the self-hosted default and fine to start, split API and queue (queue.enabled: true in Helm) when the latency-sensitive API tier and long-running workers need different scaling, and distributed runtime only once you have measured high concurrency.

Then make the tenancy argument explicitly. One deployment, five teams, isolation by three mechanisms: thread_id for short-term state, store namespaces as tuples like (tenant_id, user_id, "memories") for long-term memory, and auth handlers that stamp metadata.owner and return a filter dict applied to reads and searches. Per-team configuration is an assistant — a versioned configuration of a deployed graph — not a branch or a separate image. Reserve separate deployments for genuinely different compliance regimes or hard blast-radius requirements, and when you do split, remember that deployments must not share a Postgres database or a Redis DB number.

Finish with the platform surface: a template that bakes in async nodes, set_node_defaults, an explicit recursion_limit, pinned api_version, TTLs and a deny-by-default auth.py; CI that compiles every graph and lints for the traps; and published boundaries so exceptions are decisions rather than tickets.

Senior versus mid. A mid-level answer describes the graph architecture. A senior answer spends most of its time on isolation, configuration versioning and the defaults it will enforce, and names the one-active-run-per-thread queue rule as the constraint that shapes client UX.

System design: capacity for a launch

Prompt. "Marketing expects 500 concurrent agent conversations next month. What do you change?"

What they are probing. Whether you can do the arithmetic, and whether you know the first wall is the database rather than CPU.

The answer. Runs spend their time waiting on model APIs, so the limits are concurrency and connections. Start from N_JOBS_PER_WORKER, default 10: five hundred concurrent runs is fifty workers at the default. Then the important multiplication — LANGGRAPH_POSTGRES_POOL_MAX_SIZE defaults to 150 per replica, so fifty replicas could try to open 7,500 connections, which no managed Postgres will give you. So you lower the per-replica pool, size it against max_connections with headroom for backups, migrations and admin sessions, and only then consider a connection pooler, because a pooler is another component to operate.

Then the long-run concerns: BG_JOB_TIMEOUT_SECS defaults to 86,400, so a wedged run sits for a day unless something else kills it; Cloud HTTP connections cap at one hour regardless, so clients must rejoin with POST /threads/{thread_id}/runs/{run_id}/stream rather than hold a longer connection. BG_JOB_MAX_RETRIES defaults to 3 and resumes from the last checkpoint. Set BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS (default 180, max 3600) above your p99 super-step so deploys do not kill work mid-step.

Finally, the library-side lever: durability. Default "async" persists while the next step runs; "sync" persists before the next step and is what you want for side-effecting graphs; "exit" persists only at run exit, fastest, no mid-run recovery.

Senior versus mid. The multiplication. Candidates who have not operated this talk about autoscaling workers and never mention that the connection pool times the replica count is the number that takes down the shared database.

System design: data residency

Prompt. "A bank in Riyadh will not let conversation contents leave the Kingdom. Can we use this?"

What they are probing. Whether you know the deployment shapes and the specific controls, or whether you will promise something you cannot configure.

The answer. Yes, with the standalone Agent Server: your infrastructure, no control plane, Kubernetes with the langgraph-cloud Helm chart, your own Postgres in-region. Required environment is REDIS_URI, DATABASE_URI, LANGSMITH_API_KEY and LANGGRAPH_CLOUD_LICENSE_KEY, with LANGSMITH_ENDPOINT if pointing at self-hosted LangSmith — and no trailing slash on that endpoint, which causes auth errors. The server needs egress to https://beacon.langchain.com unless air-gapped, and the licence key is validated once at startup; both are facts to raise early, because an air-gap requirement changes the conversation.

Then the data controls. Encryption at rest with EncryptedSerializer.from_pycryptodome_aes() reading LANGGRAPH_AES_KEY, passed as serde= to the saver. Never put secrets or personal identifiers in graph state, because state is checkpointed and traced. Tracing is the part people forget: LANGSMITH_TRACING=false turns it off entirely, LangSmith anonymizers strip fields before they leave the process, and trace_policy= on add_node reduces what is emitted per node. Add TTLs so retention is a configured number rather than forever.

Then be honest about what you must verify rather than assert: the EU region exists via LANGGRAPH_HOST_URL=https://eu.api.host.langchain.com, but a Middle East hosted region is not something to claim without checking, which is exactly why the standalone shape is the answer here.

Senior versus mid. Naming tracing as an egress path. Most candidates secure the database and forget that traces carry the same message contents to a different place.

Incident response: nothing is executing

Prompt. "Pending runs are climbing, no runs complete. Go."

The answer. Triage along the run lifecycle, because it tells you the order to check. The API writes a pending run to Postgres and notifies Redis; a worker leases it, executes and checkpoints; events go back through Redis to SSE. So: are workers alive, can they reach Redis, and can they get a Postgres connection? Connection exhaustion is the most common cause and its symptom is not a LangGraph error.

Then read the shape of the graph. Steadily growing pending count with no leases points at workers or Redis. A sawtooth points at workers that lease and then die — and because a sweeper re-queues runs with lapsed heartbeats every two minutes, dying workers produce a two-minute rhythm you can see. If runs execute but hang, check for blocking I/O in async nodes: the ASGI server flags synchronous calls, and BG_JOB_ISOLATED_LOOPS=True suppresses the health-check symptom without fixing it.

What a weak answer misses. The sweeper. Without it you cannot explain re-queued runs, and you may restart workers in a loop chasing a recovery mechanism that was already working.

Incident response: one thread is stuck

Prompt. "A customer says their conversation has been frozen for two hours."

The answer. graph.get_state(config) and read next: an empty tuple means the run finished, a populated tuple names the pending node. Then read tasks — PregelTask entries carry id, name, error, interrupts and state. If there is an interrupt, this is not a technical incident: the thread is waiting on a human, and the real problem is that nobody owns the review queue. If there is an error, get_state_history(config) gives you the steps newest-first, and metadata.source tells you whether the last change was "input" (a client), "loop" (the runtime) or "update" (someone's manual update_state), which has resolved more arguments than any other field.

Recovery options, in increasing invasiveness: resume with graph.invoke(None, config); resume an interrupt with Command(resume=value) on the same thread_id; replay from a prior checkpoint by invoking with that checkpoint's config; or fork with update_state(prior_config, values, as_node=...) then invoke with None. Interrupts are always re-triggered on replay, which surprises people.

What a weak answer misses. Distinguishing "paused for a human" from "broken". They look identical on a dashboard and have completely different owners.

Incident response: the bill

Prompt. "Token spend tripled overnight and nobody deployed a model change."

The answer. First suspect a loop. The recursion limit defaults are high in 1.x — the docs say 1000 from 1.0.6, and the installed 1.2.12 code uses 10,007 super-steps (LANGGRAPH_DEFAULT_RECURSION_LIMIT). Ten thousand super-steps of an agent loop is an enormous bill arriving before any GraphRecursionError does. So: find runs with unusually high step counts, check whether a router stopped returning END, and fix the router rather than the limit — then set recursion_limit explicitly anyway, and set a sane deployment-level default as a backstop.

Second suspect retries. RetryPolicy defaults to three attempts with exponential backoff, and a node whose model call fails late will burn three calls per attempt. Third, check whether someone widened what goes into state: a growing message list is re-sent to the model and re-checkpointed every super-step, so storage and tokens inflate together.

Attribution is the real ask. Per-run token usage comes from the v3 messages projection's .usage, or from LangSmith; tag every run with tenant, assistant and flow version so the question "whose spend" has an answer.

What a weak answer misses. Saying 25 is the default recursion limit. That was pre-1.0.6 and it signals knowledge that has not been refreshed in a year.

Trade-off: durability mode

Prompt. "Why not run everything with durability='sync'?"

The answer. Because you would pay a synchronous database write before every super-step, on every graph, including ones where a rerun costs nothing. The three modes map to three different risks. "exit" persists only at run exit: fastest, and no mid-run crash recovery, which is right for short batch graphs where rerunning from scratch is cheap. "async" — the default — persists while the next step runs, so a hard crash can lose the most recent step. "sync" persists before the next step begins, so nothing is lost, at the cost of a write on the critical path.

The decision rule to state out loud: choose by side effects, not by importance. A graph that sends a message, moves money or calls a partner API needs "sync", because replaying the step would repeat the effect. A graph that only reads and reasons can take "async". Then add the complementary point — durability is not a substitute for idempotency. Nodes rerun from the start on resume, so a side effect before an interrupt() will happen twice unless you made it idempotent.

Senior versus mid. Framing it as a per-graph policy the platform publishes, not a per-call parameter each developer guesses at.

Trade-off: Agent Server or our own service

Prompt. "We already run FastAPI and Celery. Why adopt the Agent Server?"

The answer. Because the server already solves four things you would otherwise build: queuing with at most one active run per thread, streaming over SSE with rejoin, checkpointer and store injection, and an auth model with per-resource handlers and filter dicts. You can absolutely embed the library with PostgresSaver in your own service — that is a supported path — but then you own all four, and the one teams get wrong is per-thread concurrency, because the failure mode is two runs mutating one thread's state and it is intermittent.

The honest case for embedding: you have an existing platform where queuing, auth and observability already live, and adding a second runtime costs more than writing the thread lock. The dishonest case: avoiding the learning curve. Say which one you are in.

Also mention the reverse direction, because it shows breadth: the Agent Server can host other frameworks — the Claude Agent SDK, Strands, Google ADK — through the Functional API wrapper, so standardising on it can give you one deployment, auth and observability story across frameworks you did not choose.

Trade-off: arguing beta features to leadership

Prompt. "Your proposal depends on DeltaChannel and v3 streaming. Both are beta. Convince the VP."

The answer. Start by defining the label rather than defending it: in LangGraph's versioning, beta means production-safe but subject to change, distinct from alpha/experimental and from internal underscore-prefixed APIs. So the risk is not instability, it is a future migration.

Then price the alternative. Without DeltaChannel, a long thread stores its full state at every super-step, and the checkpoint table becomes the fastest-growing cost in the deployment. Without v3, you cannot stream content blocks, and per-call token usage is harder to attribute. So the question is not "beta or stable", it is "a bounded migration risk or an unbounded storage bill".

Then contain the risk, which is the part that wins the argument. Both features sit behind our own abstractions: DeltaChannel in the shared state module of the template, v3 behind a thin client wrapper, so a shape change is one file rather than every team's frontend. Pin api_version and the library version so upgrades are scheduled. And be clear about one real constraint: v3 content-block streaming requires v3 end to end, including inner graphs, so adoption is a graph-wide decision, not a per-node one.

Senior versus mid. Converting a technical label into a business comparison, then naming the containment. A mid-level answer either avoids beta features on principle or adopts them without a rollback story.

Trade-off: upgrading with live threads

Prompt. "Why is a node rename a bigger deal here than in a normal service?"

The answer. Because LangGraph applies the latest deployed code to all threads, including in-flight ones. There is no per-thread version pinning. A thread paused at an interrupt for three days resumes into today's code.

Safe changes: adding, removing or rerouting edges; adding state keys as NotRequired or optional. Unsafe: renaming or removing a node while threads are paused at it or about to enter it; renaming state keys, which silently loses their contents; narrowing types, which turns old checkpoints into validation errors.

So the procedure is add-then-remove with a drain: deploy both nodes, route new threads to the new one, let the old ones finish, confirm with a thread search on status=interrupted|busy, then delete. For logic rather than structure, stamp a flow_version in state at thread start and branch on it. And flag the Functional API as stricter: an @entrypoint replays from the start using cached task results, so adding, removing or reordering @task or interrupt() calls before a resume point corrupts resumption for every paused thread.

The sixty-second self-test

Answer out loud. Hesitation on any of these is where to spend your preparation.

What are the four components of an Agent Server, and which one holds nothing durable? What does the queue guarantee per thread, and what feature exists because of that guarantee? What is the default N_JOBS_PER_WORKER, and what do you multiply the replica count by to find your Postgres connection ceiling? What are the three durability modes and which do you choose for a graph that sends money? What is the effective recursion-limit default in installed 1.2.12, and what should you do regardless? Which authentication does a self-hosted Agent Server provide by default? What does a value returned from @auth.on.threads.create do besides stamp metadata? Which two TTL units are measured in minutes? What is the one node property that makes timeouts possible? Which three changes to a graph are unsafe while threads are paused? What does metadata.source tell you on a StateSnapshot? And which three output versions coexist, with v3 living on which method?

If you can answer all twelve without looking, you can hold the operations half of a senior LangGraph interview. The design half is practice: take the three design prompts above, draw each one on a page, and make yourself defend the connection arithmetic to someone who will push back.

These are the things that do not appear in a tutorial because they do not appear at one graph, one developer and one laptop. They appear at forty graphs, five teams and a Postgres instance somebody else also depends on. Everything here is against LangGraph 1.2.12, langgraph-cli 0.4.32 and Agent Server 0.15.1.

Traps that only appear at scale

The connection pool times the replica count. LANGGRAPH_POSTGRES_POOL_MAX_SIZE defaults to 150 per replica. Ten replicas is 1,500 connections requested from a database that probably permits a few hundred. The symptom is not a LangGraph error; it is connection exhaustion that takes down whatever else shares the instance, during the launch that caused the scale-up. Do the arithmetic before you scale, keep the product under about 70% of max_connections, and alert on the ratio rather than on a raw connection count.

The checkpoint table is the fastest-growing thing you own. A checkpointer writes a snapshot per super-step. A graph whose state holds a growing message list stores that whole list again every step. Nobody owns this table by default, so it grows until it is a billing conversation. Set checkpointer.ttl and store.ttl on day one, put table size and daily growth on the same dashboard as latency, and graph it per tenant once GET /threads/{id}/storage (server 0.16 RC) is available to you.

TTL units are minutes, and someone will read them as seconds. default_ttl: 20160 is fourteen days. default_ttl: 60 is an hour, not a minute. Write the human-readable value in a comment next to every TTL you set, in every values file.

The recursion limit will not save you. The docs say the default became 1000 in 1.0.6; the installed 1.2.12 uses 10,007 super-steps, from LANGGRAPH_DEFAULT_RECURSION_LIMIT. Either number is an enormous token bill arriving before the GraphRecursionError does. Set recursion_limit explicitly in config for every agent loop, set a sane deployment-level default as a backstop, and for loops you expect to be long, read config["metadata"]["langgraph_step"] and exit deliberately.

Sync nodes cannot be cancelled. Timeouts are async-only, and a sync node with one raises ValueError: Node timeouts are only supported for async nodes because sync Python execution cannot be safely cancelled in-process. This is not a workaround problem; it is a Python constraint. Which means "every network call is async def" is a platform rule, not a code-review preference.

set_node_defaults does not reach subgraphs. Defaults resolve at compile() time and are not inherited. A team that sets retries and timeouts once on the parent graph has an unprotected subgraph, and will find out when the subgraph is the thing that hangs. Repeat the call in every subgraph builder.

The default retry_on excludes OSError. It retries most exceptions but not ValueError, TypeError, ArithmeticError, ImportError, LookupError, NameError, SyntaxError, RuntimeError, ReferenceError, StopIteration, StopAsyncIteration or OSError, and for requests/httpx only on 5xx. That is a good default — retrying a TypeError just burns tokens — but a flaky dependency raising OSError goes unretried until you say otherwise.

Empty lists do not clear reduced keys. Returning [] through a merging reducer merges nothing; it does not reset. Use Overwrite(value) from langgraph.types to bypass the reducer. Teams discover this while trying to clear a message history and conclude the framework is broken.

Fan-out creates collisions that unit tests never see. InvalidUpdateError: At key 'k': Can receive only one value per step. appears the first time two nodes write a key in the same super-step. A graph that was correct yesterday becomes incorrect when somebody adds a Send. Reducers on every key that could ever be written in parallel are cheap insurance.

Blocking I/O in async code is suppressible and that is the danger. The ASGI server flags synchronous calls inside async nodes. --allow-blocking is local-only, and BG_JOB_ISOLATED_LOOPS=True in a deployment stops health checks failing without removing the problem. If you see that variable set, treat it as an open bug, not a configuration.

thread_id has a 255-character limit. Anything derived from a customer identifier should be hashed or a UUID. The failure is a raw database error, at the worst possible moment.

Scale-to-zero hosts lose tasks. The documentation is explicit about not running a standalone Agent Server on serverless or scale-to-zero platforms. Agents are long-running background jobs with an HTTP interface; host them like jobs.

Platform-ownership habits

Ship a template, not documentation. Documentation is advice; a template is a default. langgraph new path/to/app --template new-langgraph-project-python is the starting point, and yours should add what you do not want relitigated: async nodes throughout, set_node_defaults with retry and timeout policies, an explicit recursion_limit, a flow_version key in state, mandated metadata and tags, api_version pinned in langgraph.json, TTLs configured, and an auth.py that denies by default. Teams starting from it are compliant without trying.

Write the deny-by-default auth handler first. Self-hosted Agent Server has no default authentication. Handler precedence runs action (@auth.on.threads.create) over resource (@auth.on.threads) over global (@auth.on), so a restrictive global plus deliberate exceptions is safe, and the reverse order leaves holes you find by audit. Cover @auth.on.store too, not just threads — cross-thread memory is the gap people leave open.

Treat tracing as an egress path. Traces carry the same message contents as the database, to a different place. Decide once, in writing, whether that is acceptable, and configure accordingly: anonymizers, trace_policy= per node, LANGSMITH_TRACING=false, or an open-source path through /student-guides/langfuse. This question arrives from compliance, not engineering, and it arrives late.

Refuse pickle_fallback. JsonPlusSerializer(pickle_fallback=True) makes pandas frames round-trip and makes checkpoint deserialisation a code-execution surface. Set serde.allowed_json_modules on the server. Keep langgraph-checkpoint patched: 4.1.1 shipped a deserialisation hardening fix, which is the class of patch not to be three minors behind on.

Make "no secrets in state" a lint rule. State is checkpointed and traced, so a token in state is a token in two retained stores. Per-user credentials belong in the value returned from @auth.authenticate, which flows into run context. Webhook headers can only read LG_WEBHOOK_-prefixed variables, which is containment, not inconvenience.

Own the interrupted-thread queue explicitly. A thread paused at an interrupt is not broken, it is waiting for a person. If nobody owns that queue it grows silently and then blocks your next migration. Alert on interrupted-thread count and age, and name the owner per graph.

Pin api_version and move it deliberately. Server release streams are latest (daily), rc (every three weeks) and stable — and revisions on stable move automatically to the newest stable. That is an upgrade you did not schedule. Pin with api_version in langgraph.json or with base_image. Pin langgraph and the checkpointer packages together, because they share a serialisation contract.

Compile every graph in CI. compile() validates structure and catches a missing entrypoint (ValueError: Graph must have an entrypoint: add at least one edge from START to another node), edges to unknown nodes (Found edge ending at unknown node) and orphans, before a deploy does. It costs seconds.

Publish a shared test fixture package. The official pattern is a fresh graph per test with InMemorySaver, node isolation via compiled.nodes["name"].invoke(state), and partial execution with update_state(config, values, as_node=...) followed by invoke(..., interrupt_after=[...]). Packaging that as fixtures removes the most common excuse for untested graphs.

Run a game day before you need one. Kill a worker mid-run and time the sweeper's two-minute recovery. Exhaust the Postgres pool in staging and look at the client-side error. Send SIGTERM with RunControl wired and confirm the thread resumes. Send a fresh HumanMessage to an interrupted agent thread and read the INVALID_CHAT_HISTORY message. Three hours now, several incidents avoided.

Publish boundaries, not just capabilities. Which deployment a team lands on, what their TTL is, who answers their interrupts, and what you will not host — a DAG of batch transformations belongs in /student-guides/dagster or /student-guides/prefect, and a single stateless prompt-plus-tools belongs in create_agent from /student-guides/langchain behind a plain handler. A platform without published boundaries becomes a queue of exceptions.

Recipes worth keeping in the runbook

Find every thread that blocks your next migration. Before removing or renaming a node, search threads for status=interrupted|busy. A paused thread resumes into the newly deployed code, and there is no per-thread version pinning, so this search is the release gate. If the list is long, the answer is not to wait — it is to deploy the new node alongside the old one, route new threads to it, and come back when the old list empties.

Diagnose a thread in four calls. graph.get_state(config) and read next (an empty tuple means finished). Read tasks for PregelTask entries carrying error and interrupts. Then graph.get_state_history(config) for the steps newest-first, and on each snapshot read metadata.source — "input" means a client supplied it, "loop" means the runtime, "update" means somebody ran update_state by hand. That last value has settled more arguments than any dashboard.

Resume, replay, fork — in that order of invasiveness. Resume with graph.invoke(None, config). Resume an interrupt with Command(resume=value) on the same thread_id, or Command(resume={interrupt_id: value, ...}) when several are pending. Replay by invoking with a prior checkpoint's config, which re-executes the nodes after it. Fork with update_state(prior_config, values, as_node=...) then invoke with None. Interrupts are always re-triggered on replay, so expect to answer them again.

Fix a dangling tool call rather than retrying it. INVALID_CHAT_HISTORY means an AIMessage with tool_calls has no matching ToolMessage, usually because a client sent a fresh HumanMessage to a thread that was interrupted or hit a tool error. Resume with None or Command(resume=...), add the matching ToolMessages, or use update_state to strip the dangling calls. Then fix the client: teaching it to resume rather than re-send prevents the whole class.

Read the five fields on a timeout. NodeTimeoutError carries .node, .elapsed, .kind ("idle" or "run"), .idle_timeout and .run_timeout. Log all five and your timeout tickets diagnose themselves — "idle" points at a stalled stream, "run" at work that is genuinely too big for its budget. Writes from a timed-out attempt are discarded, which is what makes retrying one safe, and an async-generator node can yield {} as a heartbeat to reset the idle clock when slowness is legitimate.

Reduce storage without touching code. Three levers, cheapest first: set durability="exit" on batch graphs so one checkpoint is written per run instead of one per super-step; move large intermediates to UntrackedValue; and set checkpointer.ttl with "keep_latest" so a user can still resume while the history that enabled time travel is swept. Deferred deletion via LS_CHECKPOINT_DELETE moves the delete I/O off the request path once sweeps get big enough to contend with live traffic.

Check the boring deployment facts first. checkpointer.setup() and store.setup() must run once or you get missing-table errors. LANGSMITH_ENDPOINT must have no trailing slash. A standalone server needs egress to https://beacon.langchain.com unless air-gapped, and validates LANGGRAPH_CLOUD_LICENSE_KEY once at startup — which is why "the server will not boot" is sometimes a firewall rule. An image passed with --image must be linux/amd64, and --push-to is required for self-hosted and listener workspaces.

Review checklist: pull requests

Work top to bottom; the earlier items are the ones that cause incidents.

1. Every node returns a dict of state keys or a Command, on every code path. A bare return or a list produces InvalidUpdateError: Expected dict, got [...].
2. Every state key that two nodes could write in one super-step has a reducer. Clearing a reduced key uses Overwrite.
3. recursion_limit is set explicitly in the config for any loop.
4. durability is chosen deliberately: "sync" where a replayed step would repeat an external side effect.
5. Nodes that touch the network are async def, and TimeoutPolicy sets both run_timeout and idle_timeout.
6. set_node_defaults appears in the parent graph and in every subgraph builder.
7. error_handler functions contain only code that cannot fail, since a failing handler propagates.
8. No try/except wraps an interrupt(), interrupt order within a node is fixed, and side effects before an interrupt are idempotent because the node reruns from the start.
9. No secrets or personal identifiers are assigned into state.
10. No pickle_fallback=True.
11. No deprecated imports: Send and Interrupt come from langgraph.types, not langgraph.constants; context_schema= not config_schema=; retry_policy= not retry=; input_schema= not input=; durability= not checkpoint_during=; Interrupt.id not .interrupt_id; create_agent not create_react_agent; StateGraph not MessageGraph.
12. For a deployed graph: registered as a compiled variable, not a factory, and no checkpointer or store configured in code — the Agent Server injects them.
13. metadata and tags follow the platform convention so the trace is findable in six weeks.
14. Large intermediates use UntrackedValue rather than being checkpointed forty times.
15. Tests exist: at least one node tested in isolation, and one resume path tested with InMemorySaver.

Review checklist: design documents

A design document gets different questions, because the expensive mistakes are structural.

1. Which deployment shape, and why? LangSmith Cloud (serverless/dedicated), self-hosted LangSmith, hybrid/listener, or standalone. If residency drives it, say so and name the controls.
2. Which Postgres and which Redis DB number? Deployments must not share a database or a DB number. This belongs in a provisioning template, not in a human's memory.
3. Does the connection arithmetic close? Target concurrency ÷ N_JOBS_PER_WORKER gives replicas; replicas × pool size must fit max_connections with headroom.
4. What is the retention policy? checkpointer.ttl strategy ("delete" or "keep_latest") and store.ttl, in minutes, with the human-readable value stated. "keep_latest" for conversational products, "delete" for machine-to-machine.
5. Will long threads need DeltaChannel? If state grows per turn and threads live for weeks, yes — and note it is beta, with rollback caveats, and that its reducer takes (current, writes_sequence).
6. How are tenants isolated? thread_id, store namespace tuples, and which auth handlers enforce it. Which assistants exist per tenant.
7. What is the double-texting strategy? enqueue (default), reject, interrupt or rollback. Chat products usually want interrupt; anything with side effects wants enqueue or reject, never rollback.
8. How does a client survive an hour? Cloud HTTP connections cap at one hour; the client must rejoin with POST /threads/{thread_id}/runs/{run_id}/stream. Is that in the SDK wrapper, or is every team expected to implement it?
9. Which streaming version? v1 is still the default for invoke/stream; v2 is opt-in with GraphOutput; v3 lives only on stream_events() and is beta. Interrupt reads differ per version (result["__interrupt__"], result.interrupts, stream.interrupts), and v3 content blocks need v3 end to end including inner graphs.
10. What is the migration story? No node renamed or removed while threads may be paused at it; no state key renamed; no type narrowed; new keys NotRequired; a flow_version for logic changes; a thread search on status=interrupted|busy as a release gate. For Functional API code, no @task or interrupt() added, removed or reordered before a resume point.
11. What is drained on deploy? SIGTERM wired to control.request_drain, GraphDrained handled, and BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS above the p99 super-step.
12. What is alarmed? Pool utilisation, pending-run depth and age, sweeper re-queues, interrupted-thread count and age, checkpoint growth per day, NodeTimeoutError rate by node, token spend per tenant.
13. Who owns the human queue? Named, per graph.
14. Is this actually an agent? If it is a scheduled DAG, an inference-serving problem or a single stateless prompt, say so in the document and point elsewhere. Writing that down once is worth more than any of the items above.