LangChain Agent Errors: Loops, Tools, Parsing

Agent failures are frustrating because the stack trace usually points at the wrong thing. A parse error is reported at the parser, but it was caused by a prompt. A tool that is never called raises no error at all. This is a symptom-first guide: find the behaviour, then the cause, then the change.

Every one of these is easier to diagnose with tracing enabled. Debugging an agent without seeing the assembled prompt and the intermediate steps is guesswork, and the fastest fix for most of the problems below is to look at what was actually sent.

Symptom: The Agent Never Stops

The run continues past any reasonable step count, repeating similar tool calls, until an iteration cap fires or the context window fills.

Cause 1: no terminal condition the model recognises. An agent in the ReAct pattern alternates between reasoning and acting, and it stops when it decides to emit a final answer instead of another action. If the task has no clearly recognisable completion state, the model keeps acting. Tasks phrased as open-ended exploration produce this reliably; tasks with an explicit success criterion in the prompt do not.

Cause 2: a tool that never returns anything conclusive. A search tool returning near-identical results each call gives the model no new information and no reason to stop. Check whether consecutive calls differ. If they do not, the loop is the model trying the same thing repeatedly rather than making progress.

Cause 3: no cap configured. Executors and graph runtimes both provide a limit on iterations or recursion depth. It exists precisely because the model cannot be relied on to terminate. Set it low during development, low enough to fail fast, and raise it deliberately once the flow is understood.

Fixes. Set an explicit iteration or recursion limit and handle the resulting error rather than letting it surface as a crash. State the completion criterion in the system prompt in concrete terms. Give the agent an explicit tool for giving up so that “I cannot answer this” is a reachable state rather than a failure mode. And check whether the task needs an agent at all: a loop that always runs the same three steps is a chain wearing a costume, and the argument for preferring an explicit sequence is in LangChain building blocks.

The cost of this failure is worth quantifying. Each extra loop pays for the entire accumulated prompt again, so a run that goes to twelve steps instead of four does not cost three times as much, it costs more, because the scratchpad grows on every pass. The token and agent cost sizer shows how step count multiplies against prompt size.

Symptom: The Tool Is Never Called

The agent answers from its own knowledge, or says it cannot help, while a perfectly good tool sits unused.

Cause 1: the description is written for humans. Tool selection is driven by the name, the description, and the argument schema, because that is all the model sees. A description reading “Searches the database” gives the model nothing to match a user question against. One reading “Look up a customer’s current subscription tier and renewal date by customer ID. Use for any question about billing status or plan level” gives it a decision rule.

Cause 2: too many tools. Selection accuracy degrades as the tool count rises, and overlapping descriptions make it worse. If two tools could plausibly serve the same request, the model will pick inconsistently. Merge them, or make the boundary explicit in both descriptions.

Cause 3: the model does not support tool calling well. Native tool calling is a model capability, not a framework feature. Older or smaller models emulate it through prompt formatting and are substantially less reliable. Confirm the specific model supports structured tool calling before blaming the wiring.

Cause 4: the tools were never bound. Tools have to be attached to the model instance, and the object returned by that binding is the one that must be used. Passing the original unbound model to the executor is a silent no-op, and it is a common mistake because nothing errors.

Fixes. Rewrite descriptions to say what the tool returns and when to use it. Type every argument and describe it, since the schema is part of the prompt. Keep the active tool set small, and where the flow is known, route to a subset rather than exposing everything at once.

Symptom: The Tool Is Called With Bad Arguments

The tool fires but receives a malformed date, a missing required field, a string where a number belongs, or an invented identifier.

Cause: the schema is under-specified. The model fills arguments from the schema plus its own inference. An argument typed as a plain string with no description invites a guess about format. Constrained types, enumerations for fixed vocabularies, and a description giving the expected format on each field remove most of the ambiguity.

Fixes. Define arguments with a validation library so the schema carries types, constraints, and per-field descriptions into the prompt. Use enumerations wherever the valid set is closed. Never make a required argument something the model would have to invent, such as an internal ID it has no way to know; give it a lookup tool instead.

Then handle the failure path explicitly. The LangChain documentation covers returning tool errors to the model as observations rather than raising them, so the agent sees “argument ‘date’ must be YYYY-MM-DD” and retries correctly. That single change converts a class of hard failures into self-correction. Two guardrails go with it: cap the retries, or a malformed argument becomes an infinite loop by another route, and make the error messages specific, because “invalid input” tells the model nothing it can act on.

Symptom: Output Parsing Fails

The model returns something close to the requested format but not close enough: fenced code blocks around JSON, a trailing explanation, a single quote where a double quote belongs, or a truncated object.

Cause 1: parsing prose instead of requesting structure. Asking for JSON in the prompt and parsing the reply is the fragile path. Models that support structured output can be constrained to a schema directly, which removes most format errors at the source rather than catching them afterwards.

Cause 2: truncation. A response cut off by a token limit produces invalid JSON that looks like a parser bug. Check the finish reason before debugging the parser. If the output is being truncated, the fix is a higher limit or a smaller requested structure, not a more forgiving parser.

Cause 3: no retry path. Even with structured output, occasional malformed responses happen. A retry parser sends the original prompt and the failed output back to the model with the parse error attached, which recovers most single failures.

Fixes. Prefer native structured output over prompt-and-parse. Keep requested schemas shallow, since deeply nested structures fail more often and are harder to repair. Add a bounded retry. And log the raw output on every parse failure, because the failure mode is almost always visible in one glance at the actual text and invisible from the exception alone.

Symptom: Context Overflow Partway Through a Run

The first few steps succeed and then the run dies on a context length error.

Cause: the scratchpad grows monotonically. An agent’s prompt contains the system message, the tools, the conversation, and the full history of prior actions and observations. Each step appends to that history. A tool that returns a large payload, such as a full document or an unfiltered API response, can consume the remaining window in a single observation.

Fixes. Truncate or summarise tool outputs before they enter the scratchpad; return the useful fields rather than the whole response body. Trim older steps once the run passes a threshold, keeping the goal and the most recent observations. Cap retrieved context: pulling twenty chunks per step is a retrieval-tuning problem before it is a context problem, and the RAG pipeline walkthrough covers choosing that number. If long-running state is genuinely required, a checkpointed graph runtime handles it far better than a linear executor, which is one of the distinctions drawn in the framework comparison.

Symptom: Confident Wrong Answers

No error anywhere. The run completes, the output is well formed, and it is wrong.

This is the failure mode that automated checks miss entirely, and the only reliable defence is a fixed evaluation set: representative inputs with expected outcomes, rerun after every prompt, tool, or model change. Without it, a prompt tweak that fixes the case in front of you and breaks four others is indistinguishable from an improvement.

With tracing on, the diagnosis is usually quick. Read the trace in order and find the first step where the intermediate state stopped being correct. Wrong tool selected, right tool with wrong arguments, right result misinterpreted, and correct reasoning discarded at the final step are four different bugs with four different fixes, and the trace tells them apart in seconds where the final output cannot.

A Short Prevention Checklist

• Cap iterations and handle the cap as an expected outcome, not a crash.
• Type and describe every tool argument; use enumerations for closed sets.
• Return tool errors to the model as observations, with bounded retries.
• Prefer native structured output over parsing prose.
• Truncate tool outputs before they reach the scratchpad.
• Keep the active tool set small and the descriptions non-overlapping.
• Run a fixed evaluation set after every change.
• Leave tracing on in development and sample it in production.