Langchain Common Errors

---
name: langchain-common-errors
description: "Paste-match catalog of 14 real LangChain 1.0 / LangGraph 1.0 exceptions\
  \ with named\ncauses and named fixes, plus a triage decision tree. Use when you\
  \ have a traceback\nand want the specific fix, not speculative documentation. Covers\
  \ ImportError (0.2/0.3 \u2192 1.0\nmigration), AttributeError on AIMessage.content,\
  \ KeyError in LCEL and prompts,\nGraphRecursionError, silent thread_id memory loss,\
  \ JSON-serialization crashes,\nand graphs that halt without reaching END. Trigger\
  \ with \"langchain error\",\n\"langgraph traceback\", \"OutputParserException\"\
  , \"GraphRecursionError\",\n\"ImportError langchain\", \"AttributeError AIMessage\
  \ content\".\n"
allowed-tools: Read, Grep
version: 2.5.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- langchain
- langgraph
- python
- langchain-1.0
- errors
- troubleshooting
- debugging
compatibility: Designed for Claude Code
---
# LangChain Common Errors (Python)

## Overview

The same twelve-plus LangChain 1.0 / LangGraph 1.0 tracebacks show up every week
in production: `ImportError: cannot import name 'ChatOpenAI' from 'langchain.chat_models'`,
`AttributeError: 'list' object has no attribute 'lower'`, `GraphRecursionError:
Recursion limit of 25 reached`, `TypeError: Object of type datetime is not JSON
serializable`, `KeyError: 'question'` deep in LCEL internals. Stack traces are
ambiguous, docs sprawl across 0.2 / 0.3 / 1.0 eras, and engineers lose
30–90 minutes per incident re-deriving the fix.

This skill is a **paste-match catalog** of 14 entries (E01–E14) grouped into
3 reference files by category, plus a triage decision tree. Every entry opens
with the **exact exception class and message string** you see in your terminal,
names the cause in one sentence with a pain-catalog code, and gives a one-line
fix or a reference-file pointer. Pinned to `langchain-core 1.0.x`,
`langchain 1.0.x`, `langgraph 1.0.x`, verified 2026-04-21.

Pain-catalog anchors: **P02, P06, P09, P10, P16, P17, P38, P39, P40, P41, P42, P55, P56, P57, P66**.

## Prerequisites

- Python 3.10+
- A traceback or a reproducible bug — **this skill is diagnostic, not preventive**
- `langchain-core >= 1.0, < 2.0`, `langgraph >= 1.0, < 2.0`, and any provider
  integration packages pinned to `1.0.x`
- `anthropic >= 0.42` when using `langchain-anthropic` 1.0 (see E06)

## Instructions

1. **Triage first.** Read the first line of the traceback. Look up the exception
   class in the catalog below or in [Triage Decision Tree](references/errors/triage-decision-tree.md).
2. **Match the message string**, not the call site. Each catalog entry opens with
   the literal message pattern you see.
3. **Apply the named fix.** If the entry points to a reference file, read that
   file for the deep walk-through including codemods, before/after code, and
   adjacent traps. Otherwise use the one-line fix here.
4. **Verify with a test.** Every catalog entry names a test that will catch the
   error in CI next time.
5. **If no match:** check `docs/pain-catalog.md` for the exception class name or
   a message substring. Do not add speculative fixes here without catalog evidence.

## Catalog

Each entry is indexed as **E## — ClassName: "message pattern"** with a one-line
cause (pain-catalog code) and a one-line fix or reference pointer.

### Category A — Import & migration errors (0.2 / 0.3 → 1.0)

Full detail, before/after code, codemod commands: [import-migration.md](references/errors/import-migration.md).

#### E01 — `ImportError: cannot import name 'ChatOpenAI' from 'langchain.chat_models'`

- **Cause:** Top-level `langchain.chat_models` / `langchain.llms` re-exports removed in 1.0 (P38).
- **Fix:** `from langchain_openai import ChatOpenAI`. Run `python -m langchain_cli migrate` for automated rewrites. See E01 in [import-migration.md](references/errors/import-migration.md).

#### E02 — `AttributeError: module 'langchain' has no attribute 'LLMChain'`

- **Cause:** Legacy chain classes (`LLMChain`, `SequentialChain`, `TransformChain`) removed in 1.0 in favor of LCEL (P39).
- **Fix:** `chain = prompt | llm | StrOutputParser()`; `.run(x)` becomes `.invoke({"input": x})`. See E02 in [import-migration.md](references/errors/import-migration.md).

#### E03 — `ImportError: cannot import name 'ConversationBufferMemory'`

- **Cause:** All legacy memory classes removed in 1.0; LangGraph checkpointing is the replacement (P40).
- **Fix:** Use `InMemorySaver` / `PostgresSaver` + `thread_id` via LangGraph `create_react_agent`. See E03 in [import-migration.md](references/errors/import-migration.md).

#### E04 — `ImportError: cannot import name 'initialize_agent'`

- **Cause:** Legacy agent factories (`initialize_agent`, `AgentType`, `create_openai_functions_agent`) removed in 1.0 (P41).
- **Fix:** `from langgraph.prebuilt import create_react_agent`; `create_react_agent(model=llm, tools=tools, checkpointer=InMemorySaver())`. See E04 in [import-migration.md](references/errors/import-migration.md).

#### E05 — `AttributeError: 'AgentAction' object has no attribute 'tool_name'` (or inverse)

- **Cause:** Legacy `AgentAction` / `AgentFinish` shape replaced by `ToolCall` objects; fields renamed `.tool` → `.tool_name`, `.tool_input` → `.args` (P42).
- **Fix:** Access `tool_call["name"]` / `tool_call["args"]` on message `.tool_calls`, not `result["intermediate_steps"]`. See E05 in [import-migration.md](references/errors/import-migration.md).

#### E06 — `KeyError: 'input'` inside tool_use block parsing

- **Cause:** `langchain-anthropic >= 1.0` requires `anthropic >= 0.40`; SDK tool-use schema changed (P66).
- **Fix:** `pip install "langchain-anthropic>=1.0,<2.0" "anthropic>=0.42,<1.0"` in the same commit. See E06 in [import-migration.md](references/errors/import-migration.md).

### Category B — Content-shape & prompt-template errors

Full detail, block-iterator extractor, jinja2 escape pattern: [content-shape.md](references/errors/content-shape.md).

#### E07 — `AttributeError: 'list' object has no attribute 'lower'` (or `.strip`, `.split`, `.format`)

- **Cause:** `AIMessage.content` is `list[dict]` on Claude with any non-text block and on OpenAI once tools are bound (P02).
- **Fix:** Use `msg.text()` (LangChain 1.0+) or iterate and filter `block["type"] == "text"`. See E07 in [content-shape.md](references/errors/content-shape.md).

#### E08 — `KeyError: '<var>'` inside `runnables/passthrough.py` or `runnables/base.py`

- **Cause:** LCEL dict-shape mismatch between runnable stages; error surfaces at the consumer, not the producer (P06).
- **Fix:** Insert `RunnableLambda` debug probes between stages and enable `set_debug(True)`. See E08 in [content-shape.md](references/errors/content-shape.md).

#### E09 — `KeyError: '<var>'` inside `prompts/chat.py` or `prompts/prompt.py` on user input

- **Cause:** `ChatPromptTemplate.from_messages` defaults to f-string parsing; user-provided `{` / `}` characters are parsed as template variables (P57).
- **Fix:** Use `MessagesPlaceholder("history")` for variable content, or `template_format="jinja2"` for free-text templates, or escape literals as `{{` / `}}`. See E09 in [content-shape.md](references/errors/content-shape.md).

### Category C — Agent & graph execution traps

Full detail, diagnostic callbacks, thread_id middleware, router asserts: [graph-traps.md](references/errors/graph-traps.md).

#### E10 — `GraphRecursionError: Recursion limit of 25 reached without hitting a stop condition`

- **Cause:** `create_react_agent` and `StateGraph.compile()` default `recursion_limit=25` counts supersteps, not loop iterations; vague prompts never converge (P10, P55).
- **Fix:** Set `recursion_limit=10` for interactive use; add terminal edge on repeated tool-call names. See E10 in [graph-traps.md](references/errors/graph-traps.md).

#### E11 — `AgentExecutor` returns `"I couldn't find the answer"` on every tool call, no exception

- **Cause:** `handle_parsing_errors=True` catches tool exceptions and passes `str(exc)` (often empty) as observation; loop continues without signal (P09).
- **Fix:** `return_intermediate_steps=True, handle_parsing_errors=False` or migrate to LangGraph `create_react_agent`. See E11 in [graph-traps.md](references/errors/graph-traps.md).

#### E12 — Multi-turn chat forgets everything between calls, no exception

- **Cause:** LangGraph checkpointers key state by `config["configurable"]["thread_id"]`; omitted `thread_id` means every invocation gets a fresh state with no warning (P16).
- **Fix:** Require `thread_id` at app boundary; wrap in middleware that raises on missing key. See E12 in [graph-traps.md](references/errors/graph-traps.md).

#### E13 — `TypeError: Object of type <datetime / bytes / Decimal / set> is not JSON serializable`

- **Cause:** `InMemorySaver` / `PostgresSaver` / `SqliteSaver` serialize state as JSON on every superstep; non-primitives break at interrupt or checkpoint boundary (P17).
- **Fix:** Keep state JSON-primitive only (str/int/float/bool/list/dict); serialize at node boundaries; or use `JsonPlusSerializer` for Pydantic v2. See E13 in [graph-traps.md](references/errors/graph-traps.md).

#### E14 — Graph halts without reaching `END`, no exception, no log

- **Cause:** `add_conditional_edges(node, router, path_map)` where router returns a string not in `path_map` causes silent termination on some 1.0 versions (P56).
- **Fix:** `assert router_return in path_map`; always include `END` explicitly; inspect `graph.get_state(cfg).next`. See E14 in [graph-traps.md](references/errors/graph-traps.md).

## Output

- Named cause tied to a P## pain-catalog code for every traceback
- Named fix (one-line or a reference-file walk-through) tied to E## catalog entry
- A regression test pattern that catches the error in CI next time
- Triage path recorded for the incident retro (which entry matched, how long it took)

## Error Handling

This skill **is** the error-handling reference for the pack. The triage workflow:

1. **First line of traceback** → pick category in the table below.
2. **Exception class + message substring** → pick E## entry above.
3. **Reference file** → read the deep walk-through for before/after code and tests.

| First-line pattern | Category | Entries | Reference |
|---|---|---|---|
| `ImportError` from `langchain.*` | A | E01, E03, E04 | import-migration.md |
| `AttributeError` on `langchain.*` module | A | E02 | import-migration.md |
| `AttributeError` on `AgentAction` / `ToolCall` | A | E05 | import-migration.md |
| `ImportError` / `KeyError` against `langchain-anthropic` | A | E06 | import-migration.md |
| `AttributeError` on `list.lower` / `.strip` | B | E07 | content-shape.md |
| `KeyError` in `runnables/` | B | E08 | content-shape.md |
| `KeyError` in `prompts/` | B | E09 | content-shape.md |
| `GraphRecursionError` | C | E10 | graph-traps.md |
| Silent wrong answers / empty tool errors | C | E11 | graph-traps.md |
| Multi-turn memory loss, no exception | C | E12 | graph-traps.md |
| `TypeError` ... `not JSON serializable` | C | E13 | graph-traps.md |
| Graph halts without reaching `END` | C | E14 | graph-traps.md |

For tracebacks that do not match: consult [triage-decision-tree.md](references/errors/triage-decision-tree.md)
for the full routing flowchart, then `docs/pain-catalog.md` for any remaining
pain codes. Escalate to the main thread before adding speculative fixes.

## Examples

### Example 1 — `ImportError` on a 0.3 → 1.0 upgrade

Incoming traceback:

```
Traceback (most recent call last):
  File "app.py", line 3, in <module>
    from langchain.chat_models import ChatOpenAI
ImportError: cannot import name 'ChatOpenAI' from 'langchain.chat_models'
```

Triage:

1. First line is `ImportError` from `langchain.chat_models` → Category A.
2. Matches **E01** exactly.
3. Cause: top-level re-exports removed in 1.0 (P38).
4. Fix: rewrite imports and bump provider packages.

```bash
pip install "langchain-openai>=1.0,<2.0" "langchain-anthropic>=1.0,<2.0" "langchain-cli>=0.1"
python -m langchain_cli migrate src/
```

```python
# Before
from langchain.chat_models import ChatOpenAI

# After
from langchain_openai import ChatOpenAI
```

Re-run tests. Next failure is almost always **E07** (`AIMessage.content` shape)
once the imports resolve — walk that one next from [content-shape.md](references/errors/content-shape.md).

### Example 2 — `GraphRecursionError` triage

Incoming traceback:

```
Traceback (most recent call last):
  File "worker.py", line 88, in run
    result = agent.invoke({"messages": [("user", q)]}, config=cfg)
  ...
langgraph.errors.GraphRecursionError: Recursion limit of 25 reached without hitting a stop condition. You can increase the limit by setting the `recursion_limit` config key.
```

Triage:

1. Exception class is `GraphRecursionError` → Category C.
2. Matches **E10** exactly.
3. Cause: vague prompt or tool loop; default `recursion_limit=25` (P10, P55).
4. Before raising the limit, **diagnose first** — attach a `StepLogger` callback
   (see [graph-traps.md](references/errors/graph-traps.md) § E10) and count
   real steps. If the same two node names alternate, it is a convergence bug,
   not a budget bug.

Fix (budget only):

```python
cfg = {"configurable": {"thread_id": tid}, "recursion_limit": 10}
agent.invoke(inp, config=cfg)
```

Fix (convergence + budget):

```python
def _should_stop(state):
    recent = [m for m in state["messages"][-6:] if getattr(m, "tool_calls", None)]
    if len(recent) >= 3 and all(
        r.tool_calls[0]["name"] == recent[0].tool_calls[0]["name"] for r in recent
    ):
        return "end"
    return "continue"

graph.add_conditional_edges("agent", _should_stop, {"continue": "agent", "end": END})
```

Pair with a per-session token-budget middleware from `langchain-cost-tuning`.

## Resources

- Pack pain catalog: `docs/pain-catalog.md` — canonical entries for
  P02, P06, P09, P10, P16, P17, P38, P39, P40, P41, P42, P55, P56, P57, P66
- [Import & migration errors](references/errors/import-migration.md) — E01–E06
- [Content-shape & prompt errors](references/errors/content-shape.md) — E07–E09
- [Agent & graph execution traps](references/errors/graph-traps.md) — E10–E14
- [Triage decision tree](references/errors/triage-decision-tree.md) — ASCII flowchart + quick-match table
- [LangChain 1.0 release notes](https://blog.langchain.com/langchain-langgraph-1dot0/)
- [LangChain migration guide](https://python.langchain.com/docs/versions/migrating_chains/)
- LangGraph concepts
- [`langchain-cli` migrate command](https://python.langchain.com/docs/versions/migrating/)
- [`create_react_agent` reference](https://langchain-ai.github.io/langgraph/reference/prebuilt/)