{"record":{"id":"7250bf3b672113b7","repo":"vercel/ai","slug":"tool-toolname-returned-content-that-does-not","errorCode":null,"errorMessage":"Tool \"${toolName}\" returned content that does not match the expected outputSchema","messagePattern":"Tool \"(.+?)\" returned content that does not match the expected outputSchema","errorType":"exception","errorClass":"MCPClientError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/tool/mcp-client.ts","lineNumber":1316,"sourceCode":"          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) {\n          throw new MCPClientError({\n            message: `Tool \"${toolName}\" returned content that does not match the expected outputSchema`,\n            cause: parseResult.error,\n          });\n        }\n\n        return parseResult.value;\n      }\n    }\n\n    throw new MCPClientError({\n      message: `Tool \"${toolName}\" did not return structuredContent or parseable text content`,\n    });\n  }\n\n  listResources({\n    params,\n    options,\n  }: {","sourceCodeStart":1298,"sourceCodeEnd":1334,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/mcp/src/tool/mcp-client.ts#L1298-L1334","documentation":"MCPClientError thrown when a tool returns no structuredContent, so the client falls back to parsing the tool's text content as JSON against the declared outputSchema, and that parse/validation fails. The safeParseJSON error is attached as `cause`. It guards callers against text output that doesn't conform to the tool's promised schema.","triggerScenarios":"Calling a tool with an outputSchema where the server returns only text content (no structuredContent), the text is either not valid JSON or valid JSON that doesn't satisfy the schema — e.g. the server emits a human-readable message, markdown, or JSON with a different shape.","commonSituations":"Server tool updated to return prose/error text instead of JSON output; server doesn't support structured output but client declares an outputSchema; JSON payload wrapped differently (array vs object) or missing required fields; model/server emitting JSON with surrounding text so raw parse fails.","solutions":["Check error.cause (safeParseJSON result) to see if the failure is a JSON syntax error or a schema mismatch","Fix the server tool to return valid JSON text matching its declared outputSchema","Prefer having the server return structuredContent instead of JSON-in-text","If the tool legitimately returns non-JSON text, remove/loosen the outputSchema on the client"],"exampleFix":"// before: server returns plain text 'Flight booked!' but outputSchema demands JSON\nconst tool = mcpTool({ outputSchema: z.object({ status: z.string() }) });\n\n// after: make server return {\"status\":\"booked\"} as text or structuredContent,\n// or drop the schema if output is unstructured\nconst tool = mcpTool(); // no outputSchema","handlingStrategy":"validation","validationCode":"import { safeParseJSON } from '@ai-sdk/provider-utils';\n// pre-check raw text content if available before trusting schema parse:\nconst check = await safeParseJSON({ text: rawText, schema: outputSchema });\nif (!check.success) console.error('Text is not valid schema-conformant JSON:', check.error);","typeGuard":"function isTextSchemaMismatch(error: unknown): error is MCPClientError {\n  return MCPClientError.isInstance(error) && error.message.includes('returned content that does not match the expected outputSchema');\n}","tryCatchPattern":"try {\n  const value = await mcpTool.execute(args, options);\n} catch (error) {\n  if (isTextSchemaMismatch(error)) {\n    console.error('JSON/schema failure:', (error.cause as any)?.issues ?? error.cause);\n    // decide: fix server output or drop the outputSchema\n  } else {\n    throw error;\n  }\n}","preventionTips":["Prefer servers that return structuredContent instead of JSON embedded in text","Verify server tools emit pure JSON text with no surrounding prose or markdown","Keep outputSchema aligned with the server's actual JSON shape","Inspect error.cause to distinguish JSON syntax errors from schema mismatches"],"tags":["mcp","schema-validation","json-parse","tools"],"backgroundTag":"schema-validation-failed","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}