OutputParserException
langchain.schema.output_parser.OutputParserException
Stack trace
langchain_core.exceptions.OutputParserException: Could not parse LLM output: `{"name": "John", "age": "twenty"}`
File "/usr/local/lib/python3.9/site-packages/langchain/schema/output_parser.py", line 123, in parse
return self.pydantic_model.parse_raw(text)
File "/usr/local/lib/python3.9/site-packages/pydantic/main.py", line 341, in parse_raw
raise ValidationError(errors, cls) from e
pydantic.error_wrappers.ValidationError: 1 validation error for User
age
value is not a valid integer (type=type_error.integer) Why it happens
LangChain's output parsers expect the LLM to respond in a specific structured format defined by your Pydantic schema. When the LLM returns data that does not conform exactly: such as wrong types, extra text, or markdown fences: the parser raises this exception. This often happens if the prompt does not enforce strict output formatting or if the model is not instruction-tuned.
Detection
Wrap parser calls in try/except OutputParserException and log the raw LLM response to identify mismatches in expected schema before retrying or alerting.
Causes & fixes
LLM returned JSON wrapped in markdown fences (```json ... ```), causing parse failure
Add instructions to the prompt to return only raw JSON without markdown fences, or use LangChain's JsonOutputParser which strips fences automatically.
Pydantic model field types do not match the actual LLM output types (e.g., string instead of int)
Ensure your Pydantic model field types exactly match the expected output types and validate the prompt to produce correct types.
Field names in the Pydantic model do not match the keys in the LLM output JSON
Align your Pydantic model field names exactly with the keys returned by the LLM, including case sensitivity.
Using a base LLM model that ignores output format instructions
Switch to an instruction-tuned model like gpt-4o-mini or claude-3-5-haiku-20241022 that reliably follows output format instructions.
Code: broken vs fixed
from langchain.schema import BaseOutputParser
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
parser = BaseOutputParser(pydantic_model=User)
llm_response = '```json\n{"name": "John", "age": "twenty"}\n```'
user = parser.parse(llm_response) # This line raises OutputParserException
print(user)import os
from langchain.output_parsers import JsonOutputParser
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
parser = JsonOutputParser(pydantic_model=User).with_retry(n=3) # Changed to JsonOutputParser with retry
llm_response = '{"name": "John", "age": 20}' # Ensure age is int and no markdown fences
user = parser.parse(llm_response) # Now parses correctly
print(user)
# Note: Use os.environ for API keys in your actual LLM callsWorkaround
Wrap the parser call in try/except OutputParserException, catch the exception, extract JSON from the raw LLM string using regex, and parse with json.loads() as a fallback.
Prevention
Use structured outputs via OpenAI's response_format or Anthropic's tool use to guarantee schema-valid responses at the API level, bypassing parser fragility entirely.