mastra-ai/mastra · error · MastraError

AGENT_STREAM_UNKNOWN_ERROR

AGENT_STREAM_UNKNOWN_ERROR

Error message

An unknown error occurred while streaming

What it means

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).

Source

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

      _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(
        this as Agent<any, any, any, any>,
        result.result,
        preparedOptions as AgentExecutionOptions<OUTPUT>,
        threadStreamPubSub,
      );

      return result.result;
    } catch (error) {
      // Release the thread reservation taken by waitForCrossAgentThreadRun so
      // a failed setup does not block subsequent runs on this thread.

View on GitHub (pinned to 75dd419e61)

Solutions

1. Log result.status around the stream call (or inspect the returned stream/telemetry) to find which unexpected status is being produced.
2. Check for cancellation/timeout of the run: ensure the request context, AbortSignal, or workflow run is not being cancelled mid-stream.
3. Align all @mastra/core package versions (agent, core, deployer) so the execute-result status union matches what agent.ts handles.
4. Upgrade @mastra/core to the latest patch — unknown-status handling and error preservation have been improved over time.
5. If reproducible, file an issue with the runId, status value, and minimal reproduction since this error means the library hit an unclassified state.

Example fix

// before: opaque throw, no diagnostics
const stream = await agent.stream(messages);

// after: capture status and wrap with context
try {
  const stream = await agent.stream(messages);
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_STREAM_UNKNOWN_ERROR') {
    console.error('Stream ended in non-success/non-failed status', e);
    // inspect abort signals / cancellation sources before retrying
  }
  throw e;
}

function isMastraStreamError(e: unknown): e is MastraError {
  return e instanceof MastraError && typeof e.id === 'string' && e.id.startsWith('AGENT_STREAM_');
}

try {
  const stream = await agent.stream(messages);
  return stream;
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_STREAM_UNKNOWN_ERROR') {
    logger.error('Unclassified stream failure; check run status/cancellation', e);
  }
  throw e;
}

When it happens

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

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

Related errors

• 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
• AGENT_GENERATE_UNKNOWN_ERROR

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