mastra-ai/mastra · error

error

Error message

error

What it means

The stream emitted an 'error' part, and onErrorPart re-throws it verbatim, so the exposed message equals the server-side error text (here the literal 'error'). Any failure the server pushes into the stream (LLM failure, tool failure, auth problem) surfaces as this thrown Error instead of a rejected fetch.

Source

Thrown at client-sdks/client-js/src/resources/agent.ts:1643

      onStartStepPart(value) {
        // keep message id stable when we are updating an existing message:
        if (!replaceLastMessage) {
          message.id = value.messageId;
        }

        // add a step boundary part to the message
        message.parts.push({ type: 'step-start' });
        execUpdate();
      },
      onFinishMessagePart(value) {
        finishReason = value.finishReason;
        if (value.usage != null) {
          // usage = calculateLanguageModelUsage(value.usage);
          usage = value.usage;
        }
      },
      onErrorPart(error) {
        throw new Error(error);
      },
    });

    onFinish?.({ message, finishReason, usage });
  }

  /**
   * Streams a response from the agent
   * @param params - Stream parameters including prompt
   * @returns Promise containing the enhanced Response object with processDataStream method
   */
  async streamLegacy<T extends JSONSchema7 | ZodSchema | undefined = undefined>(
    params: StreamLegacyParams<T>,
  ): Promise<
    Response & {
      processDataStream: (options?: Omit<Parameters<typeof processDataStream>[0], 'stream'>) => Promise<void>;
    }
  > {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Inspect the server logs / trace for the run to find the underlying cause, since the client only sees the relayed message.
2. Add an onError handler in your consume options instead of relying on the throw, to handle stream errors gracefully.
3. Check API keys, model configuration, and tool implementations on the server.
4. Retry the request with backoff if the cause was transient (network or provider 5xx).

Example fix

// before
await agent.stream({ messages }).consume({ onErrorPart: e => { throw new Error(e); } });
// after
try {
  await agent.stream({ messages }).consume({ onErrorPart: e => log.warn('stream error part', e) });
} catch (err) {
  log.error('stream failed', err);
}

function isStreamErrorPart(part: unknown): part is { type: 'error'; message: string } {
  return typeof part === 'object' && part !== null && (part as any).type === 'error';
}

try {
  await agent.stream({ messages }).consume({ onFinish });
} catch (err) {
  console.error('Agent stream emitted an error part:', err.message);
  // check server logs/traces for the underlying cause
}

When it happens

Trigger: Calling agent.stream/streamVNext (generate path at this line) when the server emits { type: 'error', message: 'error' } during data stream processing — typically a server-side agent/tool/model failure relayed into the stream.

Common situations: Expired or missing auth causing server-side failure; LLM provider error inside a tool or workflow executed server-side; network interruption mid-stream causing the server to write an error part; server configured to send opaque error messages.

Related errors

• Codex stream error: ${JSON.stringify(payload.error ?? payloa
• UI Messages require a data property when using data- prefixe
• UI Messages require a data property when using data- prefixe
• UI Messages require a data property when using data- prefixe
• Failed to stream background tasks: ${response.statusText}

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