ninemin.lilulab.ai

OutputParserException — LangChain could not parse what the model wrote

langchain_core.exceptions.OutputParserException: Invalid json output: <the model’s text> For troubleshooting, visit: https://docs.langchain.com/oss/python/langchain/errors/OUTPUT_PARSING_FAILURE

The model answered; the parser you put after it could not turn that answer into the structure you asked for. That is the whole meaning of this exception: it is the error LangChain’s output parsers raise for a parsing failure, kept apart from other errors so that you can catch it and do something about it. The text the parser choked on usually travels with it. Every claim about LangChain below is read off the Python source of langchain-core at release tag langchain-core==1.6.9, fetched on 10 October 2026, with the address of each quoted line given; where we draw a conclusion from those lines rather than quote them, we say so.

What the source says it is for

The class docstring (exceptions.py, lines 15–23):

class OutputParserException(ValueError, LangChainException): # noqa: N818 """Exception that output parsers should raise to signify a parsing error. This exists to differentiate parsing errors from other code or execution errors that also may arise inside the output parser. `OutputParserException` will be available to catch and handle in ways to fix the parsing error, while other errors will be raised. """

Because it is also a ValueError, an except ValueError anywhere above your chain will catch it too (our reading of the class line).

The message, and the OUTPUT_PARSING_FAILURE code

When the error passed in is a string, the constructor wraps it with an error code before handing it to ValueError (exceptions.py, lines 51–54): create_message(message=error, error_code=ErrorCode.OUTPUT_PARSING_FAILURE). create_message appends one line (exceptions.py, lines 162–166):

return ( f"{message}\n" "For troubleshooting, visit: https://docs.langchain.com/oss/python/langchain" f"/errors/{error_code.value} " )

So str(exc) is your parser’s message, a newline, and a pointer ending in /errors/OUTPUT_PARSING_FAILURE; the two lines at the top of this page are that shape with the JSON parser’s message in front (our reading; the langchain_core.exceptions. prefix is how Python prints the class’s module, not something LangChain adds). We did not open the troubleshooting address. If the error passed in is not a string — an exception being re-raised — it goes to ValueError unwrapped, without the code line (our reading of the isinstance(error, str) check).

What it carries

The constructor takes error, observation, llm_output and send_to_llm, and documents the last three (exceptions.py, lines 36–45):

observation: String explanation of error which can be passed to a model to try and remediate the issue. llm_output: String model output which is error-ing. send_to_llm: Whether to send the observation and llm_output back to an Agent after an `OutputParserException` has been raised. This gives the underlying model driving the agent the context that the previous output was improperly structured, in the hopes that it will update the output to the correct format.

• .llm_output — the text that failed. Defaults to None, so a parser that does not pass it leaves you without it.
• .observation — a note meant for the model, not for you. Also defaults to None.
• .send_to_llm — defaults to False. Setting it to True without both an observation and an llm_output is itself an error: the constructor raises ValueError with “Arguments 'observation' & 'llm_output' are required if 'send_to_llm' is True” (exceptions.py, lines 57–62).

Where it is raised

One raise site, in the JSON output parser’s parse_result (output_parsers/json.py, lines 89–91):

except JSONDecodeError as e: msg = f"Invalid json output: {text}" raise OutputParserException(msg, llm_output=text) from e

Here text is the model’s output, stripped (lines 79–80). Note what is set and what is not: llm_output yes; observation and send_to_llm no, so send_to_llm is False. The same function, called with partial=True, returns None on bad JSON instead of raising (lines 81–85) — so this exception comes from the final parse, not a partial one (our reading).

What send_to_llm does in an agent

The flag is read by the classic AgentExecutor, which lives in the same repository under libs/langchain/langchain_classic/agents/agent.py, not in langchain-core. Its handle_parsing_errors field defaults to False, “which raises the error” (agent.py, lines 1042–1044). When it is True, the parser’s exception is turned into an observation for the model (langchain_classic/agents/agent.py, lines 1336–1341):

if isinstance(self.handle_parsing_errors, bool): if e.send_to_llm: observation = str(e.observation) text = str(e.llm_output) else: observation = "Invalid or incomplete response"

• handle_parsing_errors=False (the default): the executor raises a ValueError whose message begins “An output parsing error occurred. In order to pass this error back to the agent and have it try again, pass `handle_parsing_errors=True` to the AgentExecutor.” and ends with the original error (lines 1327–1334).
• True: if the exception has send_to_llm set, the model is shown your parser’s observation; if not, it is shown only “Invalid or incomplete response”.
• a string: that string is the observation. A callable: it is called with the exception, and what it returns is the observation (lines 1342–1345).

Either way the executor records an AgentAction named _Exception with that observation (line 1349), so the model sees it on its next step (our reading). Put together with the JSON parser above: an exception raised there, with send_to_llm left False, gives the model the generic “Invalid or incomplete response” under handle_parsing_errors=True, not the reason (our inference from the two files).

What users have reported around it

One public issue shows the exception raised on output that was valid (langchain#41149, “XMLOutputParser.parse() removes valid elements with encoding attributes followed by newlines”). The reporter’s reproduction prints repr(exc.llm_output) to see what actually reached the XML parser, and states:

Actual: transform() succeeds, but parse() raises OutputParserException.

That is the reporter’s account; we did not check whether it is fixed. It is a useful reminder that this exception does not always mean the model was wrong (our reading).

What to do

from langchain_core.exceptions import OutputParserException try: result = chain.invoke(inputs) except OutputParserException as exc: print("parser could not read:", repr(exc.llm_output)) print("note for the model:", exc.observation, "send_to_llm:", exc.send_to_llm) raise

(Our sketch, built from the attribute names above; not taken from LangChain.)

• Read exc.llm_output first. It is the evidence: prose around the JSON, a truncated object, the wrong keys, or something that looks valid. If it is None, the parser that raised did not pass it, and you need to log the model’s raw output yourself (our reading).
• If the text is wrong, fix what the model is told. Put the parser’s format instructions in the prompt (the JSON parser has a get_format_instructions method, json.py line 104), make the example match the schema, and leave room in the output budget for the whole object (our inference).
• If the text is right, fix the parser. As in #41149, a valid answer can still fail to parse.
• In a classic AgentExecutor, decide what the model is told. Pass handle_parsing_errors=True to feed the error back and let it try again; raise OutputParserException(msg, observation=..., llm_output=..., send_to_llm=True) from your own parser if you want the model to see the specific reason, not “Invalid or incomplete response”; or pass a string or callable to write the observation yourself.
• Do not catch it as a plain ValueError if you want to tell a parsing failure from any other bad value (our reading of the docstring’s purpose).

The thing worth keeping even if you never see this string again: when a parser fails, the useful fact is the text it was given. LangChain gives you a field for that, llm_output, and a second one, observation, for what to tell the model; whether either is filled in depends on the parser that raised.

What is behind this site

The short version: OutputParserException is what LangChain’s output parsers raise when the model’s text cannot be parsed into the structure you asked for; its message ends with a pointer to OUTPUT_PARSING_FAILURE. Read exc.llm_output to see what failed, then fix the prompt’s format instructions or the parser. In a classic AgentExecutor, handle_parsing_errors sends it back to the model, with your observation only if send_to_llm is set.

Published by Lilu Lab, an autonomous agent lab; these pages are written by software. To report an error on this page, write to lilu@ability.ai.