mastra-ai/mastra · error

Failed to stream background tasks: ${response.statusText}

Error message

Failed to stream background tasks: ${response.statusText}

What it means

MastraClient streams background tasks via GET /background-tasks/stream. When the HTTP response is not ok (e.g. 401, 404, 500), the client throws this error carrying only response.statusText, so the underlying cause is a failed HTTP request to the background-task stream endpoint.

Source

Thrown at client-sdks/client-js/src/client.ts:2354

    return this.request(`/background-tasks/${encodeURIComponent(backgroundTaskId)}`);
  }

  /**
   * Opens an SSE stream of background task events (completed/failed).
   * Returns a Response that can be consumed as a ReadableStream.
   */
  public async streamBackgroundTasks(params: StreamBackgroundTasksParams = {}) {
    const searchParams = new URLSearchParams();
    if (params.agentId) searchParams.set('agentId', params.agentId);
    if (params.runId) searchParams.set('runId', params.runId);
    if (params.threadId) searchParams.set('threadId', params.threadId);
    if (params.resourceId) searchParams.set('resourceId', params.resourceId);
    if (params.taskId) searchParams.set('taskId', params.taskId);
    const qs = searchParams.toString();
    const response: Response = await this.request(`/background-tasks/stream${qs ? `?${qs}` : ''}`, { stream: true });

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

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

    return response.body.pipeThrough(createSseJsonTransform());
  }

  /**
   * Lists schedules — agent schedules and workflow schedules — with optional
   * filtering by agentId, workflowId, or status. Agent schedules can
   * additionally be filtered by threadId, resourceId, or name.
   */
  public listSchedules(params: ListSchedulesParams = {}): Promise<ListSchedulesResponse> {
    const searchParams = new URLSearchParams();
    if (params.agentId) searchParams.set('agentId', params.agentId);
    if (params.workflowId) searchParams.set('workflowId', params.workflowId);

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Log the full response status and inspect server logs; statusText alone omits the body, so retry with fetch to see the error payload.
  2. Verify the server URL/base path and that the deployed Mastra server supports the background-tasks stream endpoint.
  3. Fix authentication (valid API key/token) if the status is 401/403.
  4. Retry with backoff if the status is 5xx (transient server error).
Defensive patterns

Strategy: try-catch

Validate before calling

// precheck availability
const res = await fetch(`${baseUrl}/background-tasks/stream`, { method: 'HEAD' });
if (!res.ok) throw new Error(`Background task streaming unavailable (HTTP ${res.status})`);

Try / catch

try {
  const stream = await client.streamBackgroundTasks(params);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failed to stream background tasks:')) {
    // inspect HTTP status via server logs or a manual request; handle 401/404/5xx
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling client.streamBackgroundTasks(...) (with optional resourceId/taskId search params) while the server returns a non-2xx status: auth failure, endpoint not available in the deployed server version, or server error opening the SSE stream.

Common situations: Mastra server not running or URL misconfigured; auth token expired; older server build without the /background-tasks/stream route (404).

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