How to Fix 'output parsing error during development' in CrewAI (TypeScript)

When CrewAI throws an output parsing error during development, it usually means the agent returned text that the framework could not convert into the structured format your task expected. In TypeScript, this shows up most often when you ask for JSON-like output, but the model responds with extra prose, malformed JSON, or a schema mismatch.

This is not a model “failure” so much as a contract failure between your task definition and the agent’s final message. The fix is usually in your prompt, output schema, or parser configuration.

The Most Common Cause

The #1 cause is asking CrewAI to return structured data without making the output contract strict enough.

In practice, this happens when you use Task.output / Task.expectedOutput with a parser or Pydantic-style schema, but your agent still has room to write free-form text. The result is a runtime error like:

• •Error: Output parsing error during development
• •Could not parse LLM output into expected format
• •Invalid JSON in tool/agent response

Broken vs fixed pattern

// ❌ Broken
import { Agent, Task, Crew } from "crewai";

const analyst = new Agent({
  role: "Data Analyst",
  goal: "Summarize customer churn",
  backstory: "You are careful and concise.",
});

const task = new Task({
  description: "Return customer churn stats as JSON.",
  expectedOutput: "A JSON object with churnRate and reasons.",
  agent: analyst,
});

// The model may return:
// "Here are the results:\n{ \"churnRate\": 0.12, \"reasons\": [\"pricing\"] }"
// That extra text breaks parsing.

// ✅ Fixed
import { z } from "zod";
import { Agent, Task, Crew } from "crewai";

const ChurnSchema = z.object({
  churnRate: z.number(),
  reasons: z.array(z.string()),
});

const analyst = new Agent({
  role: "Data Analyst",
  goal: "Summarize customer churn",
  backstory: "You return only valid JSON that matches the schema.",
});

const task = new Task({
  description: `
Return ONLY valid JSON matching this schema:
{
  "churnRate": number,
  "reasons": string[]
}
No markdown. No explanation.
`,
  expectedOutput: "Valid JSON matching the schema exactly.",
  agent: analyst,
});

If you’re using a parser hook in your wrapper code, make sure it validates after the model returns and before you hand data to downstream logic.

Other Possible Causes

1) Your prompt allows markdown or commentary

Even if the structure is correct, surrounding text breaks parsers.

// ❌ Bad prompt
description: "Give me JSON for the report and explain your reasoning."

// ✅ Better
description: `
Return ONLY raw JSON.
Do not include markdown fences, explanations, or bullet points.
`

2) Tool output is being mixed into final agent output

A tool can return valid data, but the agent appends its own summary afterward.

// ❌ Tool result gets wrapped in extra text by the agent
const task = new Task({
  description: "Use the lookup tool and return its result as-is.",
  agent,
});

Fix it by telling the agent to pass through tool output unchanged.

// ✅ Force pass-through behavior
description: `
Call the lookup tool and return its output verbatim.
Do not summarize or reformat.
`

3) Schema mismatch between what you expect and what you validate

A common TypeScript issue is expecting one shape while validating another.

// ❌ Expecting array at root
type Result = string[];

const parsed = JSON.parse(raw); // raw is actually { items: [...] }

// ✅ Match actual shape
type Result = { items: string[] };

const parsed = JSON.parse(raw);
if (!Array.isArray(parsed.items)) throw new Error("Invalid shape");

If you use Zod:

const ResultSchema = z.object({
  items: z.array(z.string()),
});

4) Model truncation caused an incomplete response

If maxTokens is too low, the model may cut off mid-object.

// ❌ Too small for structured output
new Agent({
  model: "gpt-4o-mini",
  maxTokens: 100,
});

// ✅ Give enough room for full structured output
new Agent({
  model: "gpt-4o-mini",
  maxTokens: 500,
});

This shows up as:

• •Unexpected end of JSON input
• •JSON.parse failed
• •CrewAI parsing errors after a partial response

How to Debug It

1. •

   Log the raw LLM output before parsing

   • •Don’t inspect only the parsed object.
   • •Print the exact string returned by the agent or CrewAI wrapper.

   console.log("RAW OUTPUT:", rawOutput);
   

2. •

   Check whether extra text exists around valid JSON

   • •Look for markdown fences like ```json.
   • •Look for phrases like “Sure — here’s the result”.
3. •

   Validate against a schema locally

   • •Use Zod or another validator on the raw payload.
   • •If validation fails, print the exact path that broke.

   const result = ResultSchema.safeParse(JSON.parse(rawOutput));
   if (!result.success) {
     console.error(result.error.flatten());
   }
   

4. •

   Reduce complexity

   • •Remove tools first.
   • •Remove memory next.
   • •Simplify to one task and one agent.
   • •If it works in isolation, reintroduce pieces until it breaks.

Prevention

• •

  Always specify strict output rules

  • •Say “return only valid JSON” or “return only this schema”.
  • •Do not rely on implied structure.
• •

  Validate every structured response

  • •Use Zod at runtime.
  • •Fail fast on invalid shapes instead of letting bad data spread.
• •

  Keep outputs small and explicit

  • •Large nested objects are more likely to break parsing.
  • •Prefer narrow schemas over broad free-form responses.

If you’re seeing output parsing error during development in CrewAI TypeScript, treat it as an interface contract bug. The fix is almost always in one of three places: prompt discipline, schema alignment, or response validation.

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.