mastra-ai/mastra · error · MastraError

AGENT_GENERATE_FAILED

AGENT_GENERATE_FAILED

Error message

AGENT_GENERATE_FAILED

What it means

After Agent.generate() delegates to the internal #execute() workflow, the execution result came back with status 'failed'. Mastra wraps the original error (preserving its stack trace) in an AGENT_GENERATE_FAILED MastraError so callers get a consistent error type from generate(). The root cause is always attached as the cause.

Source

Thrown at packages/core/src/agent/agent.ts:8035

      structuredOutput: mergedOptions.structuredOutput
        ? {
            ...mergedOptions.structuredOutput,
            // Convert PublicSchema to StandardSchemaWithJSON at API boundary
            // This follows the same pattern as Tool/Workflow constructors
            schema: toStandardSchema(mergedOptions.structuredOutput.schema),
          }
        : undefined,
      messages,
      methodType: 'generate',
      // Use agent's maxProcessorRetries as default, allow options to override
      maxProcessorRetries: mergedOptions.maxProcessorRetries ?? this.#maxProcessorRetries,
    } as unknown as InnerAgentExecutionOptions<any> & { _threadStreamPubSub?: PubSub };

    const result = await this.#execute(executeOptions);

    if (result.status !== 'success') {
      if (result.status === 'failed') {
        throw new MastraError(
          {
            id: 'AGENT_GENERATE_FAILED',
            domain: ErrorDomain.AGENT,
            category: ErrorCategory.USER,
          },
          // pass original error to preserve stack trace
          result.error,
        );
      }
      throw new MastraError({
        id: 'AGENT_GENERATE_UNKNOWN_ERROR',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: 'An unknown error occurred while streaming',
      });
    }

    if (typeof result.result?.getFullOutput !== 'function') {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Inspect error.cause (the original error passed to MastraError) to find the root failure — it preserves the stack trace.
2. Verify model credentials, base URLs, and rate limits for the provider.
3. Validate tool definitions/schemas and request options passed to generate().
4. Add retry logic for transient provider failures if applicable.

Example fix

try {
  await agent.generate('hi');
} catch (e) {
  console.error('generate failed:', e.cause ?? e);
}

try {
  const res = await agent.generate(prompt);
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_GENERATE_FAILED') {
    logger.error('generate failed', { cause: e.cause, stack: (e.cause as Error)?.stack });
  }
  throw e;
}

When it happens

Trigger: agent.generate() completes but the internal execution workflow's result.status === 'failed' — e.g. the underlying model call, tool, or workflow step threw and the failure propagated up through #execute().

Common situations: Invalid API keys causing provider auth failures; malformed tool schemas; model provider outages/rate limits; invalid toolChoice or unsupported parameters passed to the model.

Related errors

• AGENT_STREAM_FAILED
• AGENT_GENERATE_V1_MODEL_NOT_SUPPORTED
• AGENT_GENERATE_UNKNOWN_ERROR
• AGENT_GENERATE_MALFORMED_RESULT
• ${message.errors.join('\n') || `Claude Agent SDK failed with

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