mastra-ai/mastra · error · APIStatusError

@mastra/livekit: Mastra agent stream request failed with sta

Error message

@mastra/livekit: Mastra agent stream request failed with status ${response.status}

What it means

The remote reply generator streamed from the Mastra server endpoint `/agents/:agentId/stream` and received a non-2xx HTTP status. It wraps the failure in APIStatusError with the status code, the (safely read) response body, and a retryable hint, so callers/retry logic can decide what to do.

Source

Thrown at integrations/livekit/src/remote.ts:261

                timedOut = true;
                abortController.abort();
              }, timeoutMs);
              (watchdog as { unref?: () => void }).unref?.();

              const resolvedHeaders = await resolveHeaders(headers);
              if (cancelled) {
                clearWatchdog();
                break;
              }
              const response = await fetchImpl(url, {
                method: 'POST',
                headers: { 'content-type': 'application/json', accept: 'text/event-stream', ...resolvedHeaders },
                body: JSON.stringify(requestBody),
                signal: abortController.signal,
              });
              if (!response.ok) {
                const errorBody = await safeReadBody(response);
                throw new APIStatusError({
                  message: `@mastra/livekit: Mastra agent stream request failed with status ${response.status}`,
                  options: { statusCode: response.status, body: errorBody, retryable },
                });
              }
              if (!response.body) {
                throw new APIConnectionError({
                  message: '@mastra/livekit: Mastra agent stream returned an empty response body',
                  options: { retryable },
                });
              }

              for await (const chunk of readMastraSSE(
                response.body as unknown as globalThis.ReadableStream<Uint8Array>,
                abortController.signal,
              )) {
                if (cancelled) break;
                // First chunk: the server has committed to this generation — forbid any further
                // retry so the turn can't be replayed mid-stream. The watchdog is NOT cleared here:

View on GitHub (pinned to 75dd419e61)

Solutions

Read the `body` on the APIStatusError — it contains the server's error detail identifying the real cause.
Verify baseUrl and agentId point to a running Mastra server exposing /agents/:agentId/stream.
Check auth headers/credentials passed to the remote options if the status is 401/403.
If retryable is true, retry with backoff; otherwise fix the underlying 4xx configuration error.
Check Mastra server logs for the corresponding request failure.

Example fix

// before
remote: { baseUrl: 'https://prod.example.com', agentId: 'assistant-v1' } // agent renamed on server
// after
remote: { baseUrl: 'https://prod.example.com', agentId: 'assistant' }

Defensive patterns

Strategy: retry

Validate before calling

async function assertAgentStreamReachable(baseUrl, agentId, headers) {
  const res = await fetch(`${baseUrl.replace(/\/$/, '')}/agents/${agentId}/stream`, { method: 'HEAD' }).catch(() => null);
  if (!res || res.status === 404) throw new Error(`Agent stream endpoint unreachable for agentId=${agentId} at ${baseUrl}`);
}
// call before wiring the remote generator

Try / catch

try {
  const reply = await generateReply();
} catch (e) {
  if (e instanceof APIStatusError) {
    console.error(`Mastra stream failed: ${e.status}`, e.body);
    if (e.retryable && attempt < 3) return retryWithBackoff();
    if (e.status === 401 || e.status === 403) refreshAuthHeaders();
    if (e.status === 404) verifyAgentIdAndBaseUrl();
  }
  throw e;
}

Prevention

Log the APIStatusError body — it contains the server-side cause.
Keep agentId/baseUrl in one config source shared with the Mastra server deploy.
Alert on 5xx rates from the /agents/:id/stream route.
Add an integration test hitting the stream endpoint in CI.

When it happens

Trigger: The POST to the Mastra agent stream endpoint returns 404 (wrong agentId or baseUrl), 401/403 (bad or missing auth headers), 500 (server-side failure), or any other non-ok response.

Common situations: Misconfigured MASTRA_URL/agentId after a deploy; missing auth headers for a protected server; Mastra server down or crashing on that route; server/client API version mismatch.

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/d3ec177d9f7a6f0a. Report an issue: GitHub.