mastra-ai/mastra · error

${message.errors.join('\n') || `Claude Agent SDK failed with

Error message

${message.errors.join('\n') || `Claude Agent SDK failed with ${message.subtype}`}

What it means

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.

Source

Thrown at agent-sdks/claude/src/index.ts:307

async function runClaudeGenerate<OUTPUT>(
  prompt: string,
  options: ClaudeAgentOptions,
  telemetry: SDKAgentTelemetry<OUTPUT>,
  runOptions?: ClaudeSDKAgentRunOptions<OUTPUT>,
): Promise<SDKModelGenerateResult> {
  let text = '';
  let structuredOutputValue: unknown;
  const usage = createClaudeUsageCollector();

  for await (const message of observeClaudeMessages(
    runClaude(prompt, options, runOptions?.abortSignal ?? runOptions?.signal, runOptions),
    telemetry,
  )) {
    usage.record(message);
    if (message.type === 'result') {
      if (message.subtype !== 'success') {
        throw new Error(message.errors.join('\n') || `Claude Agent SDK failed with ${message.subtype}`);
      }

      text = message.result;
      structuredOutputValue = getClaudeStructuredOutput(message);
    }
  }

  const totals = usage.totals();
  const object = await getStructuredOutputFromValue(
    structuredOutputValue === undefined ? text : structuredOutputValue,
    runOptions?.structuredOutput,
  );

  return {
    content: [{ type: 'text', text }],
    finishReason: { unified: 'stop', raw: 'stop' },
    usage: usage.toV3Usage(),
    response: {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read message.errors content (joined into the thrown message) to identify the underlying SDK failure.
2. Verify ANTHROPIC_API_KEY / authentication and that the requested model name is valid.
3. Check Claude Agent SDK version compatibility with this agent-sdks/claude wrapper.
4. Reduce tool/permission complexity or retry if the failure was transient (rate limit, network).

// Pre-flight: ensure auth/config exist before generating
if (!process.env.ANTHROPIC_API_KEY) throw new Error('ANTHROPIC_API_KEY missing before Claude generate');

function isSuccessfulResult(m: unknown): m is { type: 'result'; subtype: 'success'; result: string } {
  return typeof m === 'object' && m !== null &&
    (m as any).type === 'result' && (m as any).subtype === 'success';
}

try {
  const res = await agent.generate(prompt);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Claude Agent SDK failed')) {
    // e.message contains joined errors or the subtype — log and retry transient cases
    logger.error({ err: e.message }, 'claude generate failed');
  } else throw e;
}

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

• Cursor run ${result.id} ended with status ${result.status}
• ClaudeSDKAgent resumeData must include sessionId or continue
• AGENT_GENERATE_V1_MODEL_NOT_SUPPORTED
• AGENT_GENERATE_FAILED
• AGENT_GENERATE_UNKNOWN_ERROR

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