How to Fix 'output parsing error' in CrewAI (Python)

What the error means

output parsing error in CrewAI usually means the agent returned text that the framework could not convert into the structure your task expected. It shows up a lot when you ask for structured output, use Pydantic models, or chain agents where one task depends on another task’s exact format.

In practice, the model answered in natural language when CrewAI expected JSON, a schema, or a specific tool/result format. The failure often bubbles up as something like OutputParserException, ValidationError, or a CrewAI task failure with parsing-related text.

The Most Common Cause

The #1 cause is asking for structured output but not constraining the agent tightly enough. If your task expects JSON or a Pydantic model, and the LLM adds extra prose, markdown fences, or partial fields, CrewAI can’t parse it.

Here’s the broken pattern versus the fixed pattern.

# Broken: vague instructions, easy to parse-break
from crewai import Agent, Task, Crew

researcher = Agent(
    role="Researcher",
    goal="Find customer churn reasons",
    backstory="You are good at analysis."
)

task = Task(
    description="Analyze churn and return JSON with reasons and confidence.",
    expected_output="JSON"
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()
print(result)

# Fixed: explicit schema + strict output contract
from pydantic import BaseModel, Field
from crewai import Agent, Task, Crew

class ChurnAnalysis(BaseModel):
    reasons: list[str] = Field(..., description="Top churn reasons")
    confidence: float = Field(..., ge=0, le=1)

researcher = Agent(
    role="Researcher",
    goal="Find customer churn reasons",
    backstory="You are good at analysis.",
    verbose=True
)

task = Task(
    description=(
        "Analyze churn. Return ONLY valid JSON matching this schema:\n"
        '{"reasons": ["..."], "confidence": 0.0}'
    ),
    expected_output="Valid JSON object only",
    output_json=ChurnAnalysis
)

crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()
print(result)

The key fix is not just “say JSON.” You need to make the output contract explicit enough that the model cannot drift into explanation mode.

Other Possible Causes

1) Markdown fences around JSON

A model may return:

{
  "reasons": ["billing issues", "slow support"],
  "confidence": 0.87
}

That looks fine to a human, but some parsers choke on the backticks. If your parser expects raw JSON, tell the agent to return no markdown at all.

description="""
Return raw JSON only.
Do not wrap in ```json fences.
Do not add commentary.
"""

2) Missing required fields in the schema

If your Pydantic model requires confidence and the model returns only reasons, CrewAI will fail during validation.

from pydantic import BaseModel

class Result(BaseModel):
    reasons: list[str]
    confidence: float  # required

# Model returns: {"reasons": ["price", "support"]}
# This triggers a validation error.

Fix it by either making fields optional or tightening the prompt so every field is always present.

class Result(BaseModel):
    reasons: list[str]
    confidence: float | None = None

3) Tool output contaminates final answer

If an agent uses tools and then summarizes tool output loosely, it may prepend text like Here is the result: before returning structured data.

# Bad instruction
description="Use tools and summarize findings."

# Better instruction
description="""
Use tools if needed.
Final answer must be raw JSON only.
No prefacing text.
No explanation.
"""

This is common when agents call search or database tools and then try to be helpful instead of machine-readable.

4) Schema mismatch between task and downstream consumer

Sometimes CrewAI parses successfully, but your own code fails because you expect a different shape than what was produced.

# Expected by code:
data["risk_score"]

# Actual output:
data["score"]

That becomes an app-level parsing problem even if CrewAI itself didn’t throw first. Keep task schema and consumer code aligned exactly.

How to Debug It

1. •

   Print the raw agent output before parsing

   • •Turn on verbose=True.
   • •Log the exact text returned by the LLM.
   • •Look for markdown fences, extra prose, missing keys, or trailing commas.
2. •

   Reduce the task to one field

   • •Start with a tiny schema like:

     class DebugOut(BaseModel):
         answer: str
     

   • •If that works, add fields back one by one.
   • •This isolates whether the issue is formatting or schema complexity.
3. •

   Check where parsing fails

   • •If you see OutputParserException, it’s usually malformed text.
   • •If you see ValidationError, the text parsed but failed schema validation.
   • •If you see tool-related errors first, inspect tool outputs before blaming CrewAI.
4. •

   Force deterministic formatting

   • •Lower randomness:

     llm_config = {"temperature": 0}
     

   • •Make instructions explicit:

     "Return ONLY valid JSON. No markdown. No explanation."
     

   • •Re-run until you get stable outputs.

Prevention

• •Use explicit schemas for every structured task.
  • •Prefer output_json or Pydantic models over “please return JSON.”
• •Keep prompts machine-first.
  • •If downstream code parses it, ban prose and markdown fences in the final answer.
• •Validate outputs at each step.
  • •Don’t let one malformed task cascade through multi-agent workflows.

If you’re building production agents with CrewAI in Python, treat output formatting as an interface contract. Once that contract is loose, parsing errors are just a matter of time.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.