mastra-ai/mastra · error · Error

Invalid structured content for tool ${request.params.name}:

Error message

Invalid structured content for tool ${request.params.name}: ${JSON.stringify(outputValidation.error)}

What it means

If a tool declares an `outputSchema`, the server validates the tool's `structuredContent` with `outputSchema.validate` after execution. On validation failure the server logs a warning and throws, preventing invalid structured output from being returned to the MCP client.

Source

Thrown at packages/mcp/src/server/server.ts:1185

        if (tool.outputSchema) {
          // Handle both cases: tools that return { structuredContent: ... } and tools that return the plain object
          let structuredContent;
          if (result && typeof result === 'object' && 'structuredContent' in result) {
            // Tool returned { structuredContent: ... } format (MCP-aware tool)
            structuredContent = result.structuredContent;
          } else {
            // Tool returned plain object, wrap it automatically for backward compatibility
            structuredContent = result;
          }

          const outputValidation = await tool.outputSchema.validate?.(structuredContent ?? {});
          if (outputValidation && !outputValidation.success) {
            this.logger.warn('Invalid structured content', {
              tool: request.params.name,
              errors: outputValidation.error,
            });
            throw new Error(
              `Invalid structured content for tool ${request.params.name}: ${JSON.stringify(outputValidation.error)}`,
            );
          }
          response.structuredContent = structuredContent;
        }

        if (response.structuredContent !== undefined) {
          const authorContent =
            result && typeof result === 'object' && 'content' in result && Array.isArray(result.content)
              ? result.content
              : undefined;
          response.content =
            authorContent && authorContent.length > 0
              ? authorContent
              : [{ type: 'text', text: JSON.stringify(response.structuredContent) }];
        } else {
          response.content = [
            {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the server log warning `Invalid structured content` — it contains the exact validation errors (also embedded in this error message).
2. Fix the tool's return value so `structuredContent` matches its declared outputSchema.
3. If the output shape is legitimately different, update the tool's outputSchema to accept it.
4. Add a unit test that runs the tool's output through its outputSchema before deploying.

Example fix

// before: outputSchema requires { result: number }
return { structuredContent: { result: '42' } };
// after
return { structuredContent: { result: 42 } };

const parsed = tool.outputSchema.safeParse(result.structuredContent ?? {}); if (!parsed.success) throw new Error(`tool output does not match outputSchema: ${parsed.error.message}`);

function matchesOutputSchema<T>(schema: ZodType<T>, value: unknown): value is T { return schema.safeParse(value).success; }

try { return await client.callTool({ name, arguments }); } catch (e) { if (String(e?.message).startsWith('Invalid structured content')) { logger.error('tool output schema mismatch', e.message); throw e; } throw e; }

When it happens

Trigger: A tool with `outputSchema` returns `structuredContent` from its execute result that fails the Zod/JSON-schema validation — wrong types, missing required fields, or extra malformed nested data.

Common situations: Tool return values shaped for an older schema after the schema was tightened, returning raw API responses instead of the schema-shaped object, or numbers-as-strings/optional fields omitted.

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

• OBSERVABILITY_INVALID_CONFIG
• OBSERVABILITY_INVALID_INSTANCE_CONFIG
• Tool must have input and output schemas defined
• MCP_CLIENT_ON_LIST_CHANGED_TOOLS_FAILED
• The "elicitation" key is now nested under "mcp.elicitation"

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/839b8f251fc02ff9. Report an issue: GitHub.