{"record":{"id":"038ebdcf09d4533b","repo":"vercel/ai","slug":"tool-toolname-returned-structuredcontent-that","errorCode":null,"errorMessage":"Tool \"${toolName}\" returned structuredContent that does not match the expected outputSchema","messagePattern":"Tool \"(.+?)\" returned structuredContent that does not match the expected outputSchema","errorType":"exception","errorClass":"MCPClientError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/tool/mcp-client.ts","lineNumber":1297,"sourceCode":"    return tools as McpToolSet<TOOL_SCHEMAS>;\n  }\n\n  /**\n   * Extracts and validates structuredContent from a tool result.\n   */\n  private async extractStructuredContent(\n    result: CallToolResult,\n    outputSchema: FlexibleSchema<unknown>,\n    toolName: string,\n  ): Promise<unknown> {\n    if ('structuredContent' in result && result.structuredContent != null) {\n      const validationResult = await safeValidateTypes({\n        value: result.structuredContent,\n        schema: asSchema(outputSchema),\n      });\n\n      if (!validationResult.success) {\n        throw new MCPClientError({\n          message: `Tool \"${toolName}\" returned structuredContent that does not match the expected outputSchema`,\n          cause: validationResult.error,\n        });\n      }\n\n      return validationResult.value;\n    }\n\n    // Fallback\n    if ('content' in result && Array.isArray(result.content)) {\n      const textContent = result.content.find(c => c.type === 'text');\n      if (textContent && 'text' in textContent) {\n        const parseResult = await safeParseJSON({\n          text: textContent.text,\n          schema: outputSchema,\n        });\n\n        if (!parseResult.success) {","sourceCodeStart":1279,"sourceCodeEnd":1315,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/mcp/src/tool/mcp-client.ts#L1279-L1315","documentation":"MCPClientError thrown after a tool call when the server returned `structuredContent` but it fails validation against the tool's declared `outputSchema`. The client validates structured output with safeValidateTypes before returning it, protecting callers from schema-violating server responses; the Zod validation error is attached as `cause`.","triggerScenarios":"Calling a tool whose server definition (or client-side outputSchema) declares an outputSchema, the server responds with structuredContent, and the payload's shape/types don't match the schema — wrong field names, missing required fields, type mismatches, or an outdated schema on the client side.","commonSituations":"Server upgraded and changed its structured output shape while the client caches an old outputSchema; client and server define divergent schemas for the same tool; server bug emitting null/undefined in required fields; numeric-vs-string type drift between implementations.","solutions":["Inspect validationResult error (error.cause) to see exactly which fields failed validation","Update the client's outputSchema to match the tool's current server-side schema","Fix the server tool so its structuredContent conforms to its declared outputSchema","Pin/align client and server tool versions so schemas agree"],"exampleFix":"// before: schema expects { result: number } but server returns { result: string }\nconst tool = mcpTool({ outputSchema: z.object({ result: z.number() }) });\n\n// after: align with the server's actual output\nconst tool = mcpTool({ outputSchema: z.object({ result: z.string() }) });","handlingStrategy":"validation","validationCode":"import { safeValidateTypes } from '@ai-sdk/provider-utils';\nimport { asSchema } from 'ai';\n// pre-check before/around the call if you have the raw structuredContent:\nconst check = await safeValidateTypes({ value: raw, schema: asSchema(outputSchema) });\nif (!check.success) console.error('structuredContent mismatch:', check.error);","typeGuard":"function isOutputSchemaMismatch(error: unknown): error is MCPClientError {\n  return MCPClientError.isInstance(error) && error.message.includes('structuredContent that does not match the expected outputSchema');\n}","tryCatchPattern":"try {\n  const value = await mcpTool.execute(args, options);\n} catch (error) {\n  if (isOutputSchemaMismatch(error)) {\n    console.error('Fields failed validation:', (error.cause as any)?.issues);\n    // update schema or handle server-side shape change\n  } else {\n    throw error;\n  }\n}","preventionTips":["Keep the client outputSchema in sync with the server tool's declared schema; regenerate after server updates","Inspect error.cause (Zod issues) to pinpoint mismatched fields","Add contract tests comparing client schema to server output samples","Make required server output fields tolerant of nullish where the spec allows"],"tags":["mcp","schema-validation","structured-output","tools"],"backgroundTag":"schema-validation-failed","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}