8.6

Symptom, cause, fix

Each error message in this manual names its cause once you know which layer raised it, and a few failures raise nothing, so look those up by their symptom.

A run fails at 2 a.m. with a message you have not seen. The message names a class from one of five packages, and the stack trace runs through LangGraph code that you did not write. You need the cause and the fix, and the section that explains it.

When you finish this section, you can look up an error message from any part of the stack. You can find its cause, its fix, and its section.

How to read the tables

Each message below is copied from a capture file or a lab recording, as the stack printed it at the pin. Rows marked "not in a capture" come from the code. A long message is cut after its first sentence or clause. Search the tables for the class name or for the first words of the message. Text in angle brackets, such as <seconds>, is a mask of the capture kit.

The last table lists failures that raise no error. Their symptom is a wrong result, a slow exit, or a tool that ran when it should not.

Models and tools

MessageCauseFixSection
ValueError: Unable to infer model provider for model='qwen3:4b'. Please specify 'model_provider' directly.a model string without a provider prefix that init_chat_model can inferwrite ollama:qwen3:4b, or pass model_provider3.2
pydantic_core._pydantic_core.ValidationError: 1 validation error for lookup_ordera tool with a ToolRuntime parameter called outside an agentcall it through the agent, or test the function under the tool3.4
Error: subtract is not a valid tool, try one of [add].the model asked for a tool that the agent does not havenone needed. The agent sends this text back to the model as a ToolMessage3.4
ValueError: ToolErrorMiddleware requires, then the names on_error and aon_error in code marksToolErrorMiddleware built with no handlerpass on_error, or aon_error for async tools3.4

Agents and middleware

MessageCauseFixSection
AssertionError: Please remove duplicate middleware instances.two instances of one middleware class in the listkeep one, or give a class its own name4.5
StructuredOutputValidationError: Failed to parse structured output for tool 'Answer': Failed to parse data to Answer: 1 validation error for AnswerToolStrategy with handle_errors=False, and a reply that failed the schemaleave handle_errors on, or handle the error in your code4.2
StructuredOutputValidationError: Failed to parse structured output for tool 'Answer': Native structured output expected valid JSON for Answer, but parsing failedProviderStrategy and a reply in plain text. It does not retry. On Ollama with tools, the first call fails this wayon Ollama with tools, leave response_format off and make one with_structured_output call after the run. On Claude, ProviderStrategy returned the value in 39 of 39 tasks4.2, 4.3
Error: Model incorrectly returned multiple structured responses (Answer, Refusal) when only one is expected.two structured calls in one model reply, sent back to the modelnone needed. The next call usually answers once4.2
ValueError: Unsupported schema type: <class 'typing._UnionGenericAlias'>.ProviderStrategy with a Union schema, raised when the agent is builtuse ToolStrategy for a union4.2
ModelCallLimitExceededError: Model call limits exceeded: run limit (1/1)ModelCallLimitMiddleware with exit_behavior="error"raise the limit, or end the run with exit_behavior="end"4.6
ToolCallLimitExceededError: Tool call limit reached: run limit exceeded (2/1 calls).ToolCallLimitMiddleware with exit_behavior="error"raise the limit, or use continue or end4.6
ValueError: ProviderToolSearchMiddleware requires a provider with server-side tool search, but got 'ollama'; supported providers: anthropic, openaia model from a provider without server-side tool searchuse an Anthropic or OpenAI model, or remove the middleware4.6
ConnectionError: third is down, not in a captureModelFallbackMiddleware, and every model in the chain failed. The run raises the last erroradd a model on another provider, and read the earlier errors in the log4.7
ModelRefusalError: Model refused to produce the requested output: I can't help with that., not in a capturea refusal block, with ModelRefusalMiddleware set to raisechange the request, or let the middleware move to a backup model4.7
PIIDetectionError: Detected 1 instance(s) of email in text contentPIIMiddleware with the strategy blockuse redact, mask, or hash when the run must go on4.8

Streaming and memory

MessageCauseFixSection
TypeError: stream_events(version='v3') / astream_events(version='v3') do not accept stream_mode;stream_mode passed to v3, which builds its own modesdrop stream_mode, and read the projections of the v3 stream5.1
NotImplementedError: stream_events(version='v2') is not supported.the sync stream_events with version v2use astream_events for v1 and v2, or v35.1
ValueError: No generations found in stream., not in a capturea stock fake chat model under create_agent with streamingtest with a real model, or with a fake that implements bind_tools and streams tool calls5.1
ValueError: Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_ida run on a graph with a checkpointer and no thread_idpass {"configurable": {"thread_id": ...}}5.2
AttributeError: 'SyncPregelLoop' object has no attribute '_put_checkpoint_fut'durability="sync" on a graph with no checkpointer, issue #9267add a checkpointer, or leave durability at its default5.3
InvalidNamespaceError: Invalid namespace label 'bob.x' found in ('users', 'bob.x'). Namespace labels cannot contain periods ('.').a store label with a periodrefuse or replace the period before the id becomes a label5.4
TypeError: Type is not msgpack serializable: Plainan instance of a plain class in the stateuse a dataclass, a Pydantic model, or a dict5.6
Deserializing unregistered type __main__.Color from checkpoint. This will be blocked in a future version.your own enum or class in a checkpoint, with no entry in allowed_msgpack_moduleslist the module and the class in allowed_msgpack_modules5.6

Graphs, interrupts, and limits

MessageCauseFixSection
InvalidUpdateError: At key 'value': Can receive only one value per step. Use an Annotated key to handle multiple values.two nodes wrote one key in the same step, and the key has no reducer. With a checkpointer, both writes are saved, so get_state, invoke(None), and every new turn on the thread raise the same error, issue #9712give the key a reducer with Annotated and deploy it, then resume with invoke(None). The thread finishes from its saved writes, with no node run again. update_state also makes the thread readable, and the old graph raises again on its next run6.1, 2.2
UnknownInterruptError: Unknown or already-consumed interrupt: <id>strict resume, set with the internal key __pregel_strict_resume, and a second answer to an interruptread the pending interrupts with get_state, and answer those6.4
RuntimeError: When there are multiple pending interrupts, you must specify the interrupt id when resuming.a plain resume value while two interrupts waitresume with a map from each interrupt id to its answer6.5
ValueError: Number of human decisions (1) does not match number of hanging tool calls (2).batched review, and fewer decisions than tool callssend one decision for each call, in order6.5
KeyError: 'checkpoint_ns'update_state with a config that has only thread_id and checkpoint_idpass the full config of a StateSnapshot from the history6.6
NodeTimeoutError: Node 'slow' exceeded its run timeout of 0.050s (elapsed: <seconds>).an async node that ran past its timeoutraise the timeout, or handle the error with an error_handler6.8
GraphRecursionError: Recursion limit of 10007 reached without hitting a stop condition.a loop with no exit, or a run that needs more steps than the limitfix the exit condition, or pass recursion_limit6.8

Integrations and the server

MessageCauseFixSection
ValueError: MCP target 'server.py' is not a valid URL.a string target that is not an http or https URLpass Path('server.py') for a stdio server7.3
MCPError: Connection closedthe stdio server exited in the middle of a call. The run raisedretry the run only when the tool is idempotent, and check the outside result first when it is not. The next call starts the server again7.3
RemoteProtocolError: Server disconnected without sending a response.the HTTP server exited in the middle of a callrestart the server, then retry the run only when the tool is idempotent. Check the outside result first when it is not7.3
MCPError: Request 'tools/call' timed outa fastmcp.Client timeout shorter than the toolraise the timeout of the client. The adapter has no timeout of its own7.3
Thread is already running a task. Wait for it to finish or choose a different multitask strategy.Agent Server, the strategy reject, and a second run on a busy thread. The status is HTTP 409retry later, or create the run with enqueue8.1
ValueError: License verification failed. Please ensure proper configuration:langgraph up with neither LANGSMITH_API_KEY nor LANGGRAPH_CLOUD_LICENSE_KEYset one of the two, or use langgraph dev8.1

Failures with no error

SymptomCauseFixSection
a tool that the reviewer did not approve ran, after an edit or a jumpbatched review, where an edit can switch tools and a middleware jump can skip the reviewset interrupt_mode="per_call"6.5
a side effect ran twice after a crash and a resumethe crash came after the tool ran and before its writes or checkpoint were saved. durability="sync" does not cover a task that just returnedkey the effect on what it means, such as the thread and the order id, and check your records first. tool_call_id and checkpoint_ns work as keys in sync and async only5.3, 2.3
one request charged twice with no crash, or twice more after a keyed resumethe model asked for the same tool call twice in one replycheck the order in your records before the charge, because a tool_call_id key lets the second call through5.3
a warning that durability has no effect when no checkpointer is presenta durability mode on a graph with no checkpointeradd a checkpointer, or drop the argument5.3
the warning PydanticSerializationUnexpectedValue for the field contexta context dict on an agent with no context_schemagive the agent a context_schema5.4
a set of tuples or a time zone came back changed from a checkpointtypes that the serializer does not rebuildstore lists, dicts, and UTC times with a zone name5.6
list_namespaces returned the namespaces of every usera prefix built from the user id *refuse * in a user id5.4
a deep agent never plans with write_todosDeep Agents 0.7 leaves out TodoListMiddlewarepass TodoListMiddleware() in middleware7.4
a script with tracing on waits at exit, or never exitsthe LangSmith endpoint is down or fails, and the exit waits for the tracescall wait_for_all_tracers(), and put a timeout on the job7.6
agent runs reached LangSmith inside tracing_context(enabled="local")LangChain code treats "local" as onuse tracing_context(enabled=False) around LangChain code7.6
the same approval was pending again after a worker crashed, and the refund row existeda resume map stays in the run config, so a crash inside the tools task loses the decisionkey the tool on what the checkpoint saved, so that the second approve is a replay9.3
the model told the customer that an order did not exist after the lookup timed outthe model did not follow the error text of the tooltest the reply to each fault in your evals, and choose a model that passes9.5
clients of a busy service got ReadTimeout, and their runs went onthe stream sent no byte while the run waited for the model serverread the thread state after a dropped stream, and add model capacity9.7
the agent read .env or deleted a dotfile although a deny rule covers /**Deep Agents passes rule patterns to wcmatch with no DOTGLOB, so * and ** skip names that start with a dotdeny /**/.* and /**/.*/** first, and allow /workspace as well as /workspace/**8.4
a user of a deep agent was told the files of another usera constant namespace factory, such as ("memories",), in StoreBackendbuild the namespace from the user id in the run context5.4
the model said that it sent the email, and no email lefta message typed over a pending approval, which Agent Chat UI closes with a placeholder tool resultmake the tool safe on its own, and disable the input while an approval is pending8.2
20 background runs of a 2 s graph with no model took 41.0 sone job per worker, the default of langgraph devstart it with --n-jobs-per-worker 10, which took 5.1 s in the same test8.1

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11