mastra-ai/mastra · error

runId is required to stream an agent builder action

Error message

runId is required to stream an agent builder action

What it means

AgentBuilder.stream() requires a runId to attach to the streaming request (sent as a runId query param) so server-side events can be correlated to the action run. An empty/undefined runId string is rejected before any network call.

Source

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

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

    return this.transformWorkflowResult(result);
  }

  /**
   * Streams agent builder action progress in real-time.
   * This calls `/agent-builder/:actionId/stream`.
   */
  async stream(
    params: AgentBuilderActionRequest,
    runId: string,
  ): Promise<globalThis.ReadableStream<{ type: string; payload: any }>> {
    if (!runId) {
      throw new Error('runId is required to stream an agent builder action');
    }

    const searchParams = new URLSearchParams();
    searchParams.set('runId', runId);

    const requestContext = parseClientRequestContext(params.requestContext);
    const { requestContext: _, ...actionParams } = params;

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

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

View on GitHub (pinned to 75dd419e61)

Solutions

1. Obtain a valid runId from the prior action/run response and pass it to stream().
2. If a run hasn't been started, invoke the non-streaming execute/run first to get a runId.
3. Validate runId is a non-empty string before calling stream().

Example fix

// before
const stream = await agentBuilder.stream(action, run?.id);
// after
if (!run?.id) throw new Error('No runId from run step');
const stream = await agentBuilder.stream(action, run.id);

function requireRunId(runId: string | undefined | null): string {
  if (typeof runId !== 'string' || runId.length === 0) {
    throw new Error('stream() requires a non-empty runId');
  }
  return runId;
}

function hasRunId(runId: unknown): runId is string {
  return typeof runId === 'string' && runId.length > 0;
}

When it happens

Trigger: Calling agentBuilder.stream(params, runId) with runId === '' or undefined — e.g. passing a variable populated from a previous step that failed to produce a runId.

Common situations: Chaining create/run calls where the runId from the first response is lost or typed as optional; copy-pasted stream call used without first starting a run.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• UI Messages require a data property when using data- prefixe
• UI Messages require a data property when using data- prefixe
• UI Messages require a data property when using data- prefixe
• MastraClient.deleteThread() requires exactly one of agentId
• Failed to parse A2A stream event: ${error instanceof Error ?

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