Troubleshooting

Common failure modes across this section, and where to go for the full explanation.

Symptom	Likely cause	Fix
`ImportError` / `ModuleNotFoundError` for a class that "used to work"	Following a pre-1.x tutorial; the class moved to `langchain-community` or was renamed in the 0.x → 1.x split	Check the migration table for the current import path.
`RateLimitError` from the provider	Too many requests too fast, especially from a wide `batch` call	Lower `max_concurrency`, add retries and fallbacks.
Context-length / token-limit error	Chat history grew unbounded over a long conversation	Apply trimming or summarization.
Retriever returns nothing relevant	Chunking or embedding mismatch, not a prompt problem	Print `retriever.invoke(question)` directly and inspect it — see the pitfall note in RAG Pipeline; also check the query and index used the same embedding model.
Model never calls a tool it clearly has access to	Vague tool name or docstring	Rewrite the description — see the pitfall note in Custom Tools.
`with_structured_output` raises or returns `parsing_error`	Schema too large, too nested, or ambiguous for the model	Flatten the schema, add field descriptions — see Structured Output and the failure-routing pattern in Structured Extraction.
Agent loops until it hits a step limit or your budget	Router never returns `END`, or the model keeps re-requesting the same tool	Set an explicit recursion/step limit — see the pitfall note in Conditional Edges.
Chain hangs, no tokens stream until the very end	A non-streaming step (e.g. an output parser) sits in the middle of the chain and buffers everything behind it	See the buffering-barrier explanation in Streaming.

tip

Most of these stop being mysterious once you look at the actual data flowing through the chain — a trace in LangSmith shows the exact input and output at every step, which is usually faster than guessing from the final error.

See also​

See also