{"record":{"id":"ec3724aadd634f74","repo":"mastra-ai/mastra","slug":"agent-stream-failed","errorCode":"AGENT_STREAM_FAILED","errorMessage":"AGENT_STREAM_FAILED","messagePattern":"AGENT_STREAM_FAILED","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/agent.ts","lineNumber":8703,"sourceCode":"            ...mergedOptions.structuredOutput,\n            // Convert PublicSchema to StandardSchemaWithJSON at API boundary\n            // This follows the same pattern as Tool/Workflow constructors\n            schema: toStandardSchema(mergedOptions.structuredOutput.schema),\n          }\n        : undefined,\n      messages,\n      methodType: 'stream',\n      // Use agent's maxProcessorRetries as default, allow options to override\n      maxProcessorRetries: mergedOptions.maxProcessorRetries ?? this.#maxProcessorRetries,\n      _threadStreamPubSub: threadStreamPubSub,\n    } as unknown as InnerAgentExecutionOptions<OUTPUT> & { _threadStreamPubSub?: PubSub };\n\n    try {\n      const result = await this.#execute(executeOptions);\n\n      if (result.status !== 'success') {\n        if (result.status === 'failed') {\n          throw new MastraError(\n            {\n              id: 'AGENT_STREAM_FAILED',\n              domain: ErrorDomain.AGENT,\n              category: ErrorCategory.USER,\n            },\n            // pass original error to preserve stack trace\n            result.error,\n          );\n        }\n        throw new MastraError({\n          id: 'AGENT_STREAM_UNKNOWN_ERROR',\n          domain: ErrorDomain.AGENT,\n          category: ErrorCategory.USER,\n          text: 'An unknown error occurred while streaming',\n        });\n      }\n\n      await agentThreadStreamRuntime.registerRun(","sourceCodeStart":8685,"sourceCodeEnd":8721,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/agent.ts#L8685-L8721","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read error.cause for the root error and its stack trace.","Verify provider credentials, quotas, and request parameters.","Validate tool schemas/inputs used during the streamed run.","Implement retry-with-backoff for transient provider errors."],"exampleFix":"try {\n  const stream = await agent.stream('hi');\n} catch (e) {\n  console.error('stream failed:', e.cause ?? e);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  const stream = await agent.stream(prompt);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'AGENT_STREAM_FAILED') {\n    logger.error('stream failed', { cause: e.cause, stack: (e.cause as Error)?.stack });\n  }\n  throw e;\n}","preventionTips":["Always inspect e.cause for the underlying provider/tool error.","Validate request parameters (temperature, maxOutputTokens) against provider limits.","Apply backoff retries for transient provider failures before surfacing to users."],"tags":["agent","streaming","execution-failed","wrapped-error"],"backgroundTag":"wrapped-execution-failure","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}