mastra-ai/mastra · error · MastraError

AGENT_STREAM_FAILED

AGENT_STREAM_FAILED

Error message

AGENT_STREAM_FAILED

What it means

When Agent.stream() internally executes via #execute() and the result status is 'failed', Mastra throws AGENT_STREAM_FAILED, attaching the original error to preserve its stack trace. The real failure (model, tool, or workflow error) lives in the cause of this error.

Source

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

            ...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: 'stream',
      // Use agent's maxProcessorRetries as default, allow options to override
      maxProcessorRetries: mergedOptions.maxProcessorRetries ?? this.#maxProcessorRetries,
      _threadStreamPubSub: threadStreamPubSub,
    } as unknown as InnerAgentExecutionOptions<OUTPUT> & { _threadStreamPubSub?: PubSub };

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

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

      await agentThreadStreamRuntime.registerRun(

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read error.cause for the root error and its stack trace.
2. Verify provider credentials, quotas, and request parameters.
3. Validate tool schemas/inputs used during the streamed run.
4. Implement retry-with-backoff for transient provider errors.

Example fix

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

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

When it happens

Trigger: agent.stream() where the internal execution result.status === 'failed' — the underlying model call or a step in the streaming execution threw before/at stream start.

Common situations: Provider authentication or quota errors surfacing at stream start; invalid tool configurations; aborts caused by bad request parameters (temperature, maxOutputTokens out of range); network failures to the provider.

Related errors

• AGENT_GENERATE_FAILED
• No result received from agent execution on iteration ${itera
• No result received from agent execution
• AGENT_STREAM_V2_MODEL_NOT_SUPPORTED
• Sub-agent ${agent.id} returned a v1 model but does not imple

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