Failed to observe agent builder action stream: ${response.st

Error message

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

What it means

observeStream() POSTs to the agent-builder action stream endpoint with stream:true and throws this error when the HTTP response status is not ok (response.ok is false). It surfaces only response.statusText, so the server rejected the streaming request before any stream data was produced. This is a transport/HTTP-level guard that fails fast instead of trying to parse a non-stream body.

Source

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

  /**
   * 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);

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

    if (!response.ok) {
      throw new Error(`Failed to observe agent builder action stream: ${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 using legacy streaming API.
   * Replays cached execution from the beginning, then continues with live stream.
   * This calls `/agent-builder/:actionId/observe-stream-legacy`.
   */
  async observeStreamLegacy(params: {
    runId: string;
  }): Promise<globalThis.ReadableStream<{ type: string; payload: any }>> {
    const searchParams = new URLSearchParams();

View on GitHub (pinned to 75dd419e61)

Solutions

Check response.statusText plus the server logs for the actual HTTP status; fix the underlying 4xx/5xx (auth, route, payload).
Verify the Mastra server version supports the agent-builder observe endpoint and that the URL/base path is correct.
Confirm authentication credentials passed to MastraClient are valid and scoped for agent-builder routes.
Retry with backoff if statusText indicates 502/503/504 from an intermediate proxy.
Wrap the call in try/catch and surface the status to the user instead of letting the stream hang.

Example fix

// before
const stream = await client.getAgentBuilder().observeStream(params); // throws bare statusText
// after
try {
  const stream = await client.getAgentBuilder().observeStream(params);
} catch (e) {
  console.error('observeStream failed:', (e as Error).message, '— check server status/auth for agent-builder routes');
}

Defensive patterns

Strategy: try-catch

Validate before calling

// nothing to validate client-side besides reachability
const health = await fetch(`${clientUrl}/health`).then(r => r.ok).catch(() => false);
if (!health) throw new Error('Mastra server unreachable before observing agent builder stream');

Type guard

function isOkResponse(res: Response): res is Response & { ok: true } { return res.ok; }

Try / catch

try {
  const stream = await builder.observeStream(params);
} catch (err) {
  console.error(`observeStream failed: ${(err as Error).message}`);
  // inspect server logs for the HTTP status; retry on 5xx, fail fast on 4xx
}

Prevention

Verify server health and auth before starting long-lived streams
Pin SDK and server versions so agent-builder routes exist
Retry with backoff only on transient 5xx statuses
Log response.statusText alongside request context for triage

When it happens

Trigger: Calling observeStream() on a ClientAgentBuilderResource when the server returns a non-2xx status: wrong/missing auth credentials, invalid action id or route path, agent-builder feature not enabled on the server, server crash or proxy returning 4xx/5xx for the streaming POST.

Common situations: Mastra server not running or deployed with agent-builder disabled; expired API key against packages/server; request hitting an older server without the agent-builder stream route; corporate proxy or gateway aborting long-lived streaming POSTs.

Related errors

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