OutputParserException
langchain.schema.output_parser.OutputParserException
Stack trace
langchain_core.exceptions.OutputParserException: Could not parse LLM output: `{"reason": "some text", "action": "some action"}`
File "/usr/local/lib/python3.9/site-packages/langchain/agents/agent.py", line 512, in parse
raise OutputParserException(f"Could not parse LLM output: `{text}`")
langchain_core.exceptions.OutputParserException: Could not parse LLM output: `{...}` Why it happens
LangChain's AgentFinish parser expects the LLM to return output strictly following a defined schema or format, often a JSON object with specific fields. If the LLM returns extra text, markdown fences, or deviates from the schema, the parser throws this exception. This often happens when prompt instructions are ambiguous or the model is not instruction-tuned.
Detection
Wrap calls to the AgentFinish parser in try/except OutputParserException and log the raw LLM output to detect format mismatches before the error crashes your app.
Causes & fixes
LLM output includes markdown fences or extra explanatory text around the JSON response
Modify the prompt to instruct the model to return ONLY the raw JSON without markdown fences or extra text, or use a parser like JsonOutputParser that strips fences automatically.
The expected output schema fields do not match the actual keys returned by the LLM
Ensure the Pydantic model or output parser schema field names exactly match the keys the LLM is instructed to produce, including case sensitivity.
Using a base model that ignores or poorly follows output format instructions
Switch to an instruction-tuned model such as gpt-4o-mini or claude-3-5-haiku-20241022 that reliably follows output format instructions.
Code: broken vs fixed
from langchain.agents import AgentExecutor
agent = AgentExecutor(...)
response = agent.run(input_text) # Raises OutputParserException due to invalid formatimport os
from langchain.agents import AgentExecutor
from langchain.output_parsers import JsonOutputParser
os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY") # Use env var for API key
agent = AgentExecutor(..., output_parser=JsonOutputParser()) # Added JsonOutputParser to handle format
response = agent.run(input_text)
print(response) # Works without parsing errorWorkaround
Catch OutputParserException, extract the JSON substring from the raw LLM output using regex, then parse it manually with json.loads() as a fallback.
Prevention
Use structured output features like OpenAI's response_format or Anthropic's tool use to enforce schema-valid responses at the API level, avoiding parser errors.