Failed to resume agent builder action stream: ${response.sta

Error message

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

What it means

resumeStream() POSTs resume parameters (plus requestContext) to the agent-builder resume endpoint with stream:true and throws this error when the response status is not ok. It guards against the server rejecting a resume of a suspended agent-builder action before any stream chunks arrive.

Source

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

    step: string | string[];
    resumeData?: unknown;
    requestContext?: RequestContext;
  }): Promise<globalThis.ReadableStream<{ type: string; payload: any }>> {
    const searchParams = new URLSearchParams();
    searchParams.set('runId', params.runId);

    const requestContext = parseClientRequestContext(params.requestContext);
    const { runId: _, requestContext: __, ...resumeParams } = params;

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

    if (!response.ok) {
      throw new Error(`Failed to resume agent builder action stream: ${response.statusText}`);
    }

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

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

  /**
   * Gets a specific action run by its ID.
   * This calls `/agent-builder/:actionId/runs/:runId`.
   * @param runId - The ID of the action run to retrieve
   * @param options - Optional configuration
   * @param options.fields - Optional array of fields to return (e.g., ['result', 'steps']). Available fields: result, error, payload, steps, activeStepsPath, serializedStepGraph. Metadata fields (runId, workflowName, resourceId, createdAt, updatedAt) and status are always included.
   * @param options.withNestedWorkflows - Whether to include nested workflow data in steps. Defaults to true. Set to false for better performance when you don't need nested workflow details.
   * @returns Promise containing the action run details with metadata and processed execution state
   */

View on GitHub (pinned to 75dd419e61)

Solutions

Inspect server logs/status for the resume request; validate the suspend payload and run id are current.
Confirm the suspended run still exists server-side (not completed/expired); otherwise start a new run instead of resuming.
Check that resumeParams match the server's expected schema (version mismatch between SDK and server).
Retry with backoff for transient 5xx.
Wrap in try/catch, and on failure re-observe via observeStream or restart the action.

Example fix

// before
const stream = await builder.resumeStream(resumeParams); // throws on non-ok
// after
try {
  const stream = await builder.resumeStream(resumeParams);
} catch (e) {
  console.error('resume failed:', (e as Error).message, '— run may be gone; restarting action');
  const fresh = await builder.stream(startParams);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// validate resume payload is complete before calling
if (!resumeParams?.runId || !resumeParams?.resumeData) {
  throw new Error('resumeParams must include runId and resumeData before resuming');
}

Type guard

function canResume(p: unknown): p is { runId: string; resumeData: unknown } {
  return !!p && typeof p === 'object' && 'runId' in p && typeof (p as any).runId === 'string';
}

Try / catch

try {
  const stream = await builder.resumeStream(resumeParams);
} catch (err) {
  console.error(`resume failed: ${(err as Error).message}`);
  // on 4xx (run gone/expired) restart the action; on 5xx retry with backoff
}

Prevention

Resume promptly; suspended runs may expire or be lost on restart
Validate the run still exists server-side before resuming
Keep resumeParams schema in sync with server version
Fall back to starting a new run when resume is rejected

When it happens

Trigger: Calling resumeStream() with an invalid/expired suspend token or run id, resuming a run that already completed or failed, auth errors, or the server returning 4xx/5xx for the resume POST.

Common situations: Resuming a workflow/action after server restart lost the suspended run; resuming after the resume snapshot expired; mismatched requestContext causing 400; server deployed without the resume route.

Related errors

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