LangChain OutputParserException because the model did not return valid JSON
langchain_core.exceptions.OutputParserException: Invalid json output:Short answer
JsonOutputParser raises OutputParserException with the text Invalid json output when the model's reply is not parseable JSON, for example JSON followed by extra text. Stop relying on prompt wording: bind the schema with with_structured_output, use create_agent with a response_format, or add an OutputFixingParser.
Fix it fast
1Find out which cause you have
Print the raw text the parser received. The exception carries it, and the message repeats it after the words Invalid json output.
try: chain.invoke({"question": "..."}) except Exception as e: print(type(e).__name__, getattr(e, "llm_output", None))2Match what you see, then jump to its fix
- 1
Invalid json output followed by JSON plus chatter, or JSON cut offA prompt | model | parser chain trusts the model to write exact JSONFix - 2
The failure happens inside an agent run, often with smaller modelsAn agent's output does not match its schemaFix - 3
The model has no tool or schema support, so the parser is the only optionYou must keep a text parser and need a second attemptFix
- 1
What does the error look like?
langchain_core.exceptions.OutputParserException: Invalid json output:
Cause 1 of 3
A prompt | model | parser chain trusts the model to write exact JSON
1Check
In langchain-core, JsonOutputParser turns a JSONDecodeError into OutputParserException with the stripped model text. LangChain's structured output page says chains have no built-in retry for parse failures.
grep -rn "JsonOutputParser\|PydanticOutputParser" --include='*.py' .2Fix
Bind the schema to the model with with_structured_output. When the provider supports native structured output, LangChain says it enforces the schema and avoids most parsing failures.
from pydantic import BaseModel
class Answer(BaseModel):
city: str
reason: str
structured = model.with_structured_output(Answer)
result = structured.invoke("Where should we host the conference?")3Verify
The result is an Answer object, not text.
print(type(result), result)Confirmed by docs.langchain.com
Cause 2 of 3
An agent's output does not match its schema
1Check
In create_agent, ToolStrategy has handle_errors set to True by default: a bad structured output goes back to the model as a ToolMessage so it can retry. If someone set handle_errors=False, the error is raised instead.
grep -rn "handle_errors\|response_format" --include='*.py' .2Fix
Use response_format with ToolStrategy and leave handle_errors on, or give it a custom message.
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy
agent = create_agent(
model=model,
tools=[],
response_format=ToolStrategy(Answer, handle_errors=True),
)3Verify
The result carries a validated structured_response.
result = agent.invoke({"messages": [{"role": "user", "content": "Where should we host it?"}]})
print(result["structured_response"])Confirmed by docs.langchain.com
Cause 3 of 3
You must keep a text parser and need a second attempt
1Check
OutputFixingParser, from langchain-classic, sends the broken output, the format instructions and the error back to a model, then parses the corrected reply. max_retries sets the number of fix attempts.
python -m pip show langchain-classic2Fix
Wrap your parser in OutputFixingParser. It does not see the original prompt; RetryOutputParser does, but it cannot be the last piped step.
from langchain_classic.output_parsers import OutputFixingParser
fixing = OutputFixingParser.from_llm(parser=parser, llm=model, max_retries=3)3Verify
A reply that used to fail now parses.
print(fixing.parse(bad_text))Confirmed by docs.langchain.com
How do I stop it coming back?
- Prefer with_structured_output or response_format over format instructions in the prompt.
- Catch OutputParserException at the edge of the chain and log the raw text.
- Do not let a parse failure retry forever; cap retries.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
AI
Azure OpenAI says the API deployment for this resource does not exist
The API deployment for this resource does not exist
Azure OpenAI does not take a model name in the model field.
2 causes, each with a fixAI
Azure OpenAI fails with an SSL certificate verification error
httpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED]
The client checks the endpoint's certificate against its CA bundle, which is certifi by default.
2 causes, each with a fixAI
LangChain says it could not import the chromadb package
ImportError: Could not import chromadb python package. Please install it with `pip install chromadb`.
The message comes from LangChain's old Chroma class, which cannot import chromadb in the Python that runs your code.
2 causes, each with a fixAI
Gemini API returns 429 RESOURCE_EXHAUSTED on the free tier
429 RESOURCE_EXHAUSTED
Gemini limits are applied per Google Cloud project, not per API key, so a new key in the same project does not reset anything.
3 causes, each with a fixAI
ChatPromptTemplate is missing the variable agent_scratchpad
Expected: ['agent_scratchpad', 'input']
A tool-calling agent keeps its tool calls and tool results in a prompt slot named agent_scratchpad.
2 causes, each with a fixAI
LangChain no longer exports AgentExecutor from langchain.agents
ImportError: cannot import name 'AgentExecutor' from 'langchain.agents'
LangChain v1 moved legacy classes into a separate package called langchain-classic, and AgentExecutor lives there now.
2 causes, each with a fix