mastra-ai/mastra · error

Failed to observe agent builder action stream legacy: ${resp

Error message

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

What it means

observeStreamLegacy() performs the same ok-check as observeStream but against the legacy agent-builder stream endpoint, throwing this error when the HTTP status is not ok. It exists for backward compatibility and is called by stream(). The message distinguishes the legacy route so failures can be attributed to it.

Source

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

  /**
   * 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();
    searchParams.set('runId', params.runId);

    const url = `/agent-builder/${this.actionId}/observe-stream-legacy?${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 legacy: ${response.statusText}`);
    }

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

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

  /**
   * Resumes a suspended agent builder action and streams the results.
   * This calls `/agent-builder/:actionId/resume-stream`.
   */
  async resumeStream(params: {
    runId: string;
    step: string | string[];
    resumeData?: unknown;
    requestContext?: RequestContext;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check the HTTP status in server logs; fix auth/route/payload accordingly.
2. If the server removed the legacy route, migrate to the non-legacy observeStream API.
3. Confirm SDK and server versions are compatible (legacy endpoint availability).
4. Retry with backoff for transient 5xx from proxies.
5. Catch and log the statusText with request context before surfacing to users.

Example fix

// before
const stream = await builder.stream(params); // legacy path throws bare statusText
// after
try {
  const stream = await builder.stream(params);
} catch (e) {
  console.error('legacy observe stream failed:', (e as Error).message);
  // fall back to non-legacy API if server no longer supports it
  const stream2 = await builder.observeStream(params);
}

const legacyAvailable = await fetch(`${base}/agent-builder/stream/legacy-probe`, { method: 'OPTIONS' }).then(r => r.ok).catch(() => false);
if (!legacyAvailable) console.warn('Legacy agent-builder stream route unavailable; use observeStream');

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

try {
  const stream = await builder.stream(params);
} catch (err) {
  console.error(`legacy stream failed: ${(err as Error).message}`);
  const stream = await builder.observeStream(params); // migrate/fallback
}

When it happens

Trigger: Calling stream() (which delegates to observeStreamLegacy) when the legacy endpoint returns non-2xx: server removed or disabled the legacy route, wrong action/record id, auth failure, or proxy error on the streaming POST.

Common situations: Server upgraded to the new agent-builder stream API and legacy route returns 404/410; clients pinned to old SDK shapes hitting new servers; expired credentials; gateway timeouts on long-lived streams.

Related errors

• Failed to stream background tasks: ${response.statusText}
• Failed to stream agent builder action: ${response.statusText
• Failed to observe agent builder action stream: ${response.st
• Failed to resume agent builder action stream: ${response.sta
• @mastra/livekit: Mastra agent stream request failed with sta

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