{"record":{"id":"6ecac1c98b742abb","repo":"mastra-ai/mastra","slug":"agent-stream-unknown-error","errorCode":"AGENT_STREAM_UNKNOWN_ERROR","errorMessage":"An unknown error occurred while streaming","messagePattern":"An unknown error occurred while streaming","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/agent.ts","lineNumber":8713,"sourceCode":"      _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(\n        this as Agent<any, any, any, any>,\n        result.result,\n        preparedOptions as AgentExecutionOptions<OUTPUT>,\n        threadStreamPubSub,\n      );\n\n      return result.result;\n    } catch (error) {\n      // Release the thread reservation taken by waitForCrossAgentThreadRun so\n      // a failed setup does not block subsequent runs on this thread.","sourceCodeStart":8695,"sourceCodeEnd":8731,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/agent.ts#L8695-L8731","documentation":"AGENT_STREAM_UNKNOWN_ERROR is a catch-all thrown by Agent.stream when #execute() returns a result whose status is neither 'success' nor 'failed'. The library cannot classify the failure, so it throws a generic MastraError with no underlying error attached (unlike the 'failed' branch which preserves the original error's stack trace).","triggerScenarios":"Calling agent.stream() (or streamVNext) and the internal #execute() call resolves with result.status set to an unexpected non-'success', non-'failed' value (e.g. 'aborted' or an internal status). Any code path where the execution loop ends without success and without a captured error lands here.","commonSituations":"Runs aborted by cancellation/timeouts where the executor reports an 'aborted' or other status instead of 'failed'; internal executor state machine bugs; mismatched versions of @mastra/core packages where the execute result union includes a status the agent code does not handle.","solutions":["Log result.status around the stream call (or inspect the returned stream/telemetry) to find which unexpected status is being produced.","Check for cancellation/timeout of the run: ensure the request context, AbortSignal, or workflow run is not being cancelled mid-stream.","Align all @mastra/core package versions (agent, core, deployer) so the execute-result status union matches what agent.ts handles.","Upgrade @mastra/core to the latest patch — unknown-status handling and error preservation have been improved over time.","If reproducible, file an issue with the runId, status value, and minimal reproduction since this error means the library hit an unclassified state."],"exampleFix":"// before: opaque throw, no diagnostics\nconst stream = await agent.stream(messages);\n\n// after: capture status and wrap with context\ntry {\n  const stream = await agent.stream(messages);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'AGENT_STREAM_UNKNOWN_ERROR') {\n    console.error('Stream ended in non-success/non-failed status', e);\n    // inspect abort signals / cancellation sources before retrying\n  }\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isMastraStreamError(e: unknown): e is MastraError {\n  return e instanceof MastraError && typeof e.id === 'string' && e.id.startsWith('AGENT_STREAM_');\n}","tryCatchPattern":"try {\n  const stream = await agent.stream(messages);\n  return stream;\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'AGENT_STREAM_UNKNOWN_ERROR') {\n    logger.error('Unclassified stream failure; check run status/cancellation', e);\n  }\n  throw e;\n}","preventionTips":["Keep all @mastra/core packages on the same version so execute-result status unions match.","Avoid cancelling/aborting runs mid-stream unless you handle the resulting non-success status.","Always wrap stream calls in try/catch and log MastraError.id for diagnostics.","Pin and regularly update @mastra/core; unknown-status handling improves over releases."],"tags":["agent","streaming","unknown-status","mastra-core"],"backgroundTag":"unknown-stream-error","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}