ComposioHQ/composio · error · Error

experimental_subAgent() structured output failed schema vali

Error message

experimental_subAgent() structured output failed schema validation: ${summarizeValidationError(validation.error)}

What it means

When experimental_subAgent() is called with a Zod schema, the subagent's parsed JSON output is re-validated with zodSchema.safeParse. If the model's output conforms to JSON syntax but violates the schema, this error embeds a summarized Zod validation failure.

Source

Thrown at ts/packages/cli/src/services/run-subagent-shared.ts:235

  [
    'Your previous response was not valid structured output.',
    'Do not read files. Do not run terminal commands. Do not inspect the workspace again.',
    'Reuse the analysis you already completed.',
    toolName
      ? `If the MCP tool \`${toolName}\` is available, call it exactly once with the final structured result. Otherwise reply with only raw JSON matching the schema.`
      : 'Reply with only raw JSON matching the schema.',
    'Do not include prose, markdown fences, or any extra text.',
    JSON.stringify(structuredSchema, null, 2),
  ].join('\n');

export const validateStructuredOutput = (
  parsed: unknown,
  options: InvokeAgentNormalizedOptions
): unknown => {
  if (options.zodSchema && typeof options.zodSchema.safeParse === 'function') {
    const validation = options.zodSchema.safeParse(parsed);
    if (!validation.success) {
      throw new Error(
        `experimental_subAgent() structured output failed schema validation: ${summarizeValidationError(validation.error)}`
      );
    }

    return validation.data;
  }

  return parsed;
};

const tryParseStructuredJson = (text: string): unknown | undefined => {
  const trimmed = text.trim();
  if (!trimmed) {
    return undefined;
  }

  // A parse failure here is the signal to fall through to more permissive
  // extraction for agents that emit a short status line before the final JSON

View on GitHub (pinned to 64b1b85502)

Solutions

Loosen or correct the schema to match realistic model output (e.g. z.coerce.number(), optional fields)
Strengthen the prompt to explicitly specify the exact JSON shape matching the schema
Retry the subagent call; LLM output is nondeterministic and may validate on another attempt
Pre-validate/repair the raw output before safeParse if you control the parsing path

Example fix

// before
const s = z.object({ count: z.number() });
// after
const s = z.object({ count: z.coerce.number() }); // model often emits "5"

Defensive patterns

Strategy: retry

Validate before calling

const probe = schema.safeParse(candidateOutput); if (!probe.success) { /* re-prompt the subagent with the Zod issue summary */ }

Try / catch

catch (e) { if (e instanceof Error && e.message.includes('failed schema validation')) { return await experimental_subAgent(prompt, { schema }); /* retry once */ } throw e; }

Prevention

Use z.coerce for numeric/boolean fields models commonly stringify
Keep schemas permissive (passthrough/optional) for LLM output
Retry once or twice before surfacing the failure

When it happens

Trigger: experimental_subAgent(prompt, { schema: z.object({ count: z.number() }) }) where the subagent returns {"count":"five"}, extra/missing required fields, wrong nesting, or string-vs-number type mismatches in the JSON it emits.

Common situations: LLM subagents returning numbers as strings, adding unexpected fields when the schema is strict, omitting optional-looking but required fields, or an over-strict schema that does not match what the prompt asks for.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/43312378739571f1. Report an issue: GitHub.