mastra-ai/mastra · error

Workflow ID is required

Error message

Workflow ID is required

What it means

Inside the workflowRoute handler, after resolving the workflow either from the fixed `workflow` option or the `:workflowId` path param, neither was available. This is a request-time guard ensuring the handler never streams an unknown workflow.

Source

Thrown at client-sdks/ai-sdk/src/workflow-route.ts:279

      const params = (await c.req.json()) as WorkflowStreamHandlerParams;
      const mastra = c.get('mastra');
      const contextRequestContext = (c as any).get('requestContext') as RequestContext | undefined;

      let workflowToUse: string | undefined = workflow;
      if (!workflow) {
        const workflowId = c.req.param('workflowId');
        workflowToUse = workflowId;
      }

      if (c.req.param('workflowId') && workflow) {
        mastra
          .getLogger()
          ?.warn(
            `Fixed workflow ID was set together with a workflowId path parameter. This can lead to unexpected behavior.`,
          );
      }
      if (!workflowToUse) {
        throw new Error('Workflow ID is required');
      }

      const handlerOptions = {
        mastra,
        workflowId: workflowToUse,
        params: {
          ...params,
          requestContext: contextRequestContext || params.requestContext,
        },
        includeTextStreamParts,
        sendReasoning,
        sendSources,
      };

      if (version === 'v7') {
        const uiMessageStream = await handleWorkflowStream({
          ...handlerOptions,
          version: 'v7',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure the request URL includes the workflow ID in the :workflowId segment.
2. Re-register the route with a fixed `workflow` option if the path is static.
3. Check server route registration logs; also note the warning about setting both a fixed workflow and a path param, which can conflict.

Example fix

// before
await fetch('/api/workflow/run', { method: 'POST', ... });
// after
await fetch('/api/workflows/myWorkflowId/run', { method: 'POST', ... });

// client side
const workflowId = extractParam(url, 'workflowId');
if (!workflowId) throw new Error('workflowId path param is required for this endpoint');

try {
  await streamWorkflow(url);
} catch (e) {
  if (e instanceof Error && e.message === 'Workflow ID is required') {
    // fix request URL / route registration
  }
  throw e;
}

When it happens

Trigger: Requesting a route registered with workflowRoute where the path is missing the ':workflowId' param value at request time, or the route was registered without a fixed workflow and the request URL omitted workflowId.

Common situations: Hitting a misregistered route directly (e.g. POST /api/workflow without an ID); a reverse proxy stripping path params; mixing a fixed workflow ID with a workflowId path param such that resolution fails.

Related errors

• Agent ${agentId} not found
• Path must include :agentId to route to the correct agent or
• Agent ID is required
• Agent ${agentId} not found
• Path must include :agentId to route to the correct agent or

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