langchain-common-errors

What this skill does

# 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 (P1