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

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.

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)

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.