Path must include :workflowId to route to the correct workfl

Error message

Path must include :workflowId to route to the correct workflow or pass the workflow explicitly

What it means

workflowRoute() creates an AI-SDK-compatible streaming POST route for workflows. When no explicit `workflow` is passed, the route path must contain a `:workflowId` param so the handler can resolve which workflow to run at request time. If both are missing, Mastra cannot know which workflow the route targets, so it throws this error at registration time.

Source

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

 * });
 *
 * @example
 * // Fixed workflow with custom path
 * workflowRoute({
 *   path: '/api/data-pipeline/stream',
 *   workflow: 'data-processing-workflow',
 * });
 */
export function workflowRoute({
  path = '/api/workflows/:workflowId/stream',
  workflow,
  version = 'v5',
  includeTextStreamParts = true,
  sendReasoning = false,
  sendSources = false,
}: WorkflowRouteOptions): ReturnType<typeof registerApiRoute> {
  if (!workflow && !path.includes('/:workflowId')) {
    throw new Error('Path must include :workflowId to route to the correct workflow or pass the workflow explicitly');
  }

  return registerApiRoute(path, {
    method: 'POST',
    openapi: {
      summary: 'Stream a workflow in AI SDK format',
      description: 'Starts a workflow run and streams events as AI SDK UIMessage chunks',
      tags: ['ai-sdk'],
      parameters: [
        {
          name: 'workflowId',
          in: 'path',
          required: true,
          description: 'The ID of the workflow to stream',
          schema: { type: 'string' },
        },
      ],
      requestBody: {

View on GitHub (pinned to 75dd419e61)

Solutions

Add ':workflowId' to the route path, e.g. '/api/workflows/:workflowId/stream'.
Or pass an explicit `workflow` instance in the options so the path doesn't need the param.
If using a fixed path intentionally, pass the workflow to bind the route to it.

Example fix

// before
workflowRoute({ path: '/api/workflow/run', mastra });
// after
workflowRoute({ path: '/api/workflows/:workflowId/run', mastra });
// or: workflowRoute({ path: '/api/workflow/run', mastra, workflow: myWorkflow });

Defensive patterns

Strategy: validation

Validate before calling

function assertWorkflowRouteOptions(path: string, opts: { workflow?: unknown }) {
  if (!opts.workflow && !path.includes('/:workflowId')) {
    throw new Error('workflowRoute requires a `workflow` option or a path containing :workflowId');
  }
}

Prevention

Wrap workflowRoute registration in a helper that asserts the path contains :workflowId when no workflow is passed.
Centralize route path constants so the :workflowId segment can't be dropped by hand.
Add a startup smoke test that registers all routes.

When it happens

Trigger: Calling workflowRoute({ path: '/api/workflows/run', ... }) with a path lacking ':workflowId' and without passing the `workflow` option in WorkflowRouteOptions.

Common situations: Registering a catch-all workflow route during Mastra server setup and forgetting the dynamic segment; copy-pasting a route template from an agent route; renaming the path and accidentally dropping the param.

Related errors

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