Failed to stream agent builder action

Error message

Failed to stream agent builder action: ${response.statusText}

What it means

The agent-builder stream POST returned a non-ok HTTP status. The client throws with only response.statusText, so the actual failure reason must be inferred from the status code and server logs.

Solutions

Check the numeric status (capture response.status in a wrapper, since this message only has statusText).
Verify authentication/credentials for the agent-builder API.
Confirm the runId exists server-side and the action params match AgentBuilderActionRequest schema.
Retry with backoff for 5xx statuses.

Defensive patterns

Strategy: retry

Validate before calling

if (!runId) throw new Error('runId required before streaming');
if (!params || typeof params !== 'object') throw new Error('action params required');

Try / catch

try {
  const stream = await agentBuilder.stream(action, runId);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failed to stream agent builder action:')) {
    // distinguish auth (401/403), validation (400), not-found runId (404), retry 5xx with backoff
  }
  throw e;
}

Prevention

Validate action params against AgentBuilderActionRequest before sending.
Refresh credentials before long-running streaming sessions.
Verify the runId exists server-side and retry transient 5xx with backoff.

When it happens

Trigger: Calling agentBuilder.stream(action, runId) when the server rejects the request: invalid action params, bad requestContext, auth failure, runId not found, or server error during stream setup.

Common situations: Expired/missing credentials against the builder server; referencing a runId that no longer exists; sending action params that fail server-side validation (400).

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

    if (!runId) {
      throw new Error('runId is required to stream an agent builder action');
    }

    const searchParams = new URLSearchParams();
    searchParams.set('runId', runId);

    const requestContext = parseClientRequestContext(params.requestContext);
    const { requestContext: _, ...actionParams } = params;

    const url = `/agent-builder/${this.actionId}/stream?${searchParams.toString()}`;
    const response: Response = await this.request(url, {
      method: 'POST',
      body: { ...actionParams, requestContext },
      stream: true,
    });

    if (!response.ok) {
      throw new Error(`Failed to stream agent builder action: ${response.statusText}`);
    }

    if (!response.body) {
      throw new Error('Response body is null');
    }

    return response.body.pipeThrough(this.createRecordParserTransform());
  }

  /**
   * Observes an existing agent builder action run stream.
   * Replays cached execution from the beginning, then continues with live stream.
   * This is the recommended method for recovery after page refresh/hot reload.
   * This calls `/agent-builder/:actionId/observe`
   */
  async observeStream(params: { runId: string }): Promise<globalThis.ReadableStream<{ type: string; payload: any }>> {
    const searchParams = new URLSearchParams();
    searchParams.set('runId', params.runId);

View on GitHub (pinned to 75dd419e61)