OutputParserException
langchain_core.exceptions.OutputParserException
Stack trace
langchain_core.exceptions.OutputParserException: Could not parse LLM output: `Agent returned invalid output format. Expected action with tool name and input, got: {raw_response}`
File "/usr/local/lib/python3.11/site-packages/langchain_core/agents/agent.py", line 234, in _parse_output
raise OutputParserException(
File "/usr/local/lib/python3.11/site-packages/langchain_core/agents/react/output_parser.py", line 45, in parse
raise OutputParserException(f"Could not parse LLM output: `{text}`") Why it happens
LangChain agents (especially ReAct agents) expect the LLM to respond in a strict format: either an immediate final Answer or an Action/Action Input pair that calls a tool. When the LLM returns unstructured text, markdown fences, preamble, or a malformed action format, the ReActOutputParser cannot map it to an AgentFinish or AgentAction object. This is common with non-instruction-tuned models, vague prompts, or when the LLM's internal reasoning leaks into the expected output structure.
Detection
Log the raw LLM output before parsing by wrapping the agent execution in try/except OutputParserException, then inspect the caught exception's message. Add print(intermediate_steps) in the agent loop to see which step produced malformed output.
Causes & fixes
LLM returned unstructured text or reasoning instead of 'Action: tool_name' format
Add to your prompt: 'When using a tool, ALWAYS respond with exactly: Action: [tool_name]\nAction Input: [input]' and use gpt-4o-mini or claude-3-5-haiku-20241022 which follow format instructions reliably.
LLM wrapped the action in markdown code fences (```action: tool_name```)
Use create_react_agent with a chat model that supports structured output, or add 'Return raw text only: no markdown, no backticks, no code fences' to the prompt.
Tool name in the action doesn't exactly match any registered tool
Ensure the LLM knows the exact tool names. Pass tools to create_react_agent, then inject their names into the prompt explicitly with tools_str = '\n'.join([f'{tool.name}: {tool.description}' for tool in tools]).
Agent is returning 'Final Answer: ...' instead of 'Action: ...' but parser expects AgentFinish format
Verify the prompt instructs the agent when to use 'Final Answer' vs 'Action'. Use the default prompt from create_react_agent which handles this automatically.
Code: broken vs fixed
from langchain_core.agents import AgentExecutor
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
import os
@tool
def multiply(a: int, b: int) -> int:
"""Multiply two numbers."""
return a * b
tools = [multiply]
llm = ChatOpenAI(model="gpt-4o", api_key=os.environ.get("OPENAI_API_KEY"))
# BROKEN: Custom prompt with vague format instructions
custom_prompt = """You are a helpful assistant. Use tools when needed.
If you use a tool, explain what you're doing and then respond naturally."""
from langchain_core.agents import create_react_agent
agent = create_react_agent(llm, tools, prompt=custom_prompt) # This will parse incorrectly
executor = AgentExecutor.from_agent_and_tools(agent, tools, verbose=True)
try:
result = executor.invoke({"input": "multiply 5 by 3"})
except Exception as e:
print(f"ERROR: {e}") # OutputParserException: Could not parse LLM outputfrom langchain_core.agents import AgentExecutor, create_react_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langchain import hub
import os
@tool
def multiply(a: int, b: int) -> int:
"""Multiply two numbers."""
return a * b
tools = [multiply]
llm = ChatOpenAI(model="gpt-4o-mini", api_key=os.environ.get("OPENAI_API_KEY"))
# FIXED: Use the battle-tested ReAct prompt from hub instead of custom format
prompt = hub.pull("hwchase17/react")
agent = create_react_agent(llm, tools, prompt=prompt)
executor = AgentExecutor.from_agent_and_tools(agent, tools, verbose=True)
try:
result = executor.invoke({"input": "multiply 5 by 3"})
print(f"SUCCESS: {result['output']}")
except Exception as e:
print(f"ERROR: {e}")Workaround
Wrap the agent executor call in a retry loop: catch OutputParserException, then retry up to 3 times with an explicit format instruction injected into the next call. Extract the LLM's raw response from the exception, manually parse it for 'Action:' keywords using regex, and construct an AgentAction manually if parsing fails.
Prevention
Build agents using LangGraph StateGraph for complex workflows: it provides explicit state transitions and error handling instead of relying on fragile output parsing. For simple agents, always use the official prompt from hub.pull() and gpt-4o-mini or claude-3-5-haiku-20241022. Consider OpenAI's function_calling or Anthropic's tool_use which return structured output directly, bypassing parsing fragility.