{"record":{"id":"839b8f251fc02ff9","repo":"mastra-ai/mastra","slug":"invalid-structured-content-for-tool-request-para","errorCode":null,"errorMessage":"Invalid structured content for tool ${request.params.name}: ${JSON.stringify(outputValidation.error)}","messagePattern":"Invalid structured content for tool (.+?): (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/server/server.ts","lineNumber":1185,"sourceCode":"\n        if (tool.outputSchema) {\n          // Handle both cases: tools that return { structuredContent: ... } and tools that return the plain object\n          let structuredContent;\n          if (result && typeof result === 'object' && 'structuredContent' in result) {\n            // Tool returned { structuredContent: ... } format (MCP-aware tool)\n            structuredContent = result.structuredContent;\n          } else {\n            // Tool returned plain object, wrap it automatically for backward compatibility\n            structuredContent = result;\n          }\n\n          const outputValidation = await tool.outputSchema.validate?.(structuredContent ?? {});\n          if (outputValidation && !outputValidation.success) {\n            this.logger.warn('Invalid structured content', {\n              tool: request.params.name,\n              errors: outputValidation.error,\n            });\n            throw new Error(\n              `Invalid structured content for tool ${request.params.name}: ${JSON.stringify(outputValidation.error)}`,\n            );\n          }\n          response.structuredContent = structuredContent;\n        }\n\n        if (response.structuredContent !== undefined) {\n          const authorContent =\n            result && typeof result === 'object' && 'content' in result && Array.isArray(result.content)\n              ? result.content\n              : undefined;\n          response.content =\n            authorContent && authorContent.length > 0\n              ? authorContent\n              : [{ type: 'text', text: JSON.stringify(response.structuredContent) }];\n        } else {\n          response.content = [\n            {","sourceCodeStart":1167,"sourceCodeEnd":1203,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/server/server.ts#L1167-L1203","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the server log warning `Invalid structured content` — it contains the exact validation errors (also embedded in this error message).","Fix the tool's return value so `structuredContent` matches its declared outputSchema.","If the output shape is legitimately different, update the tool's outputSchema to accept it.","Add a unit test that runs the tool's output through its outputSchema before deploying."],"exampleFix":"// before: outputSchema requires { result: number }\nreturn { structuredContent: { result: '42' } };\n// after\nreturn { structuredContent: { result: 42 } };","handlingStrategy":"validation","validationCode":"const parsed = tool.outputSchema.safeParse(result.structuredContent ?? {}); if (!parsed.success) throw new Error(`tool output does not match outputSchema: ${parsed.error.message}`);","typeGuard":"function matchesOutputSchema<T>(schema: ZodType<T>, value: unknown): value is T { return schema.safeParse(value).success; }","tryCatchPattern":"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; }","preventionTips":["Unit-test each tool's return value against its outputSchema.","Derive the return type from the schema (z.infer) instead of hand-writing it.","Re-run output tests whenever outputSchema changes."],"tags":["mcp","schema-validation","tools","zod"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}