{"record":{"id":"83ef33412ae3ceea","repo":"mastra-ai/mastra","slug":"message-errors-join-n-claude-agent-sdk-f","errorCode":null,"errorMessage":"${message.errors.join('\\n') || `Claude Agent SDK failed with ${message.subtype}`}","messagePattern":"\\$\\{message\\.errors\\.join\\('\\\\n'\\) \\|\\| `Claude Agent SDK failed with \\$\\{message\\.subtype\\}`\\}","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent-sdks/claude/src/index.ts","lineNumber":307,"sourceCode":"\nasync function runClaudeGenerate<OUTPUT>(\n  prompt: string,\n  options: ClaudeAgentOptions,\n  telemetry: SDKAgentTelemetry<OUTPUT>,\n  runOptions?: ClaudeSDKAgentRunOptions<OUTPUT>,\n): Promise<SDKModelGenerateResult> {\n  let text = '';\n  let structuredOutputValue: unknown;\n  const usage = createClaudeUsageCollector();\n\n  for await (const message of observeClaudeMessages(\n    runClaude(prompt, options, runOptions?.abortSignal ?? runOptions?.signal, runOptions),\n    telemetry,\n  )) {\n    usage.record(message);\n    if (message.type === 'result') {\n      if (message.subtype !== 'success') {\n        throw new Error(message.errors.join('\\n') || `Claude Agent SDK failed with ${message.subtype}`);\n      }\n\n      text = message.result;\n      structuredOutputValue = getClaudeStructuredOutput(message);\n    }\n  }\n\n  const totals = usage.totals();\n  const object = await getStructuredOutputFromValue(\n    structuredOutputValue === undefined ? text : structuredOutputValue,\n    runOptions?.structuredOutput,\n  );\n\n  return {\n    content: [{ type: 'text', text }],\n    finishReason: { unified: 'stop', raw: 'stop' },\n    usage: usage.toV3Usage(),\n    response: {","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/agent-sdks/claude/src/index.ts#L289-L325","documentation":"runClaudeGenerate iterates Claude Agent SDK messages; when the final result message has a subtype other than 'success', the run failed. The thrown message joins the SDK-provided error strings, or falls back to 'Claude Agent SDK failed with <subtype>' when no errors were reported.","triggerScenarios":"await agent.generate(prompt) where the underlying Claude Agent SDK run completes with a non-success result subtype (e.g. error_during_execution, max_usage_limit reached) — i.e. message.type === 'result' && message.subtype !== 'success'.","commonSituations":"Invalid API key or model name; the Claude CLI process failing mid-run; hitting usage/rate limits; the agent refusing or aborting a turn; tool execution errors surfacing as a failed result subtype.","solutions":["Read message.errors content (joined into the thrown message) to identify the underlying SDK failure.","Verify ANTHROPIC_API_KEY / authentication and that the requested model name is valid.","Check Claude Agent SDK version compatibility with this agent-sdks/claude wrapper.","Reduce tool/permission complexity or retry if the failure was transient (rate limit, network)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Pre-flight: ensure auth/config exist before generating\nif (!process.env.ANTHROPIC_API_KEY) throw new Error('ANTHROPIC_API_KEY missing before Claude generate');","typeGuard":"function isSuccessfulResult(m: unknown): m is { type: 'result'; subtype: 'success'; result: string } {\n  return typeof m === 'object' && m !== null &&\n    (m as any).type === 'result' && (m as any).subtype === 'success';\n}","tryCatchPattern":"try {\n  const res = await agent.generate(prompt);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Claude Agent SDK failed')) {\n    // e.message contains joined errors or the subtype — log and retry transient cases\n    logger.error({ err: e.message }, 'claude generate failed');\n  } else throw e;\n}","preventionTips":["Verify ANTHROPIC_API_KEY and model names in CI before runs.","Monitor usage/rate limits; add backoff on transient subtypes.","Pin and test a compatible Claude Agent SDK version."],"tags":["claude","agent-sdk","runtime-failure","generate"],"backgroundTag":"agent-run-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}