{"record":{"id":"349bbcfe93111e25","repo":"mastra-ai/mastra","slug":"path-must-include-workflowid-to-route-to-the-corr","errorCode":null,"errorMessage":"Path must include :workflowId to route to the correct workflow or pass the workflow explicitly","messagePattern":"Path must include :workflowId to route to the correct workflow or pass the workflow explicitly","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/ai-sdk/src/workflow-route.ts","lineNumber":212,"sourceCode":" * });\n *\n * @example\n * // Fixed workflow with custom path\n * workflowRoute({\n *   path: '/api/data-pipeline/stream',\n *   workflow: 'data-processing-workflow',\n * });\n */\nexport function workflowRoute({\n  path = '/api/workflows/:workflowId/stream',\n  workflow,\n  version = 'v5',\n  includeTextStreamParts = true,\n  sendReasoning = false,\n  sendSources = false,\n}: WorkflowRouteOptions): ReturnType<typeof registerApiRoute> {\n  if (!workflow && !path.includes('/:workflowId')) {\n    throw new Error('Path must include :workflowId to route to the correct workflow or pass the workflow explicitly');\n  }\n\n  return registerApiRoute(path, {\n    method: 'POST',\n    openapi: {\n      summary: 'Stream a workflow in AI SDK format',\n      description: 'Starts a workflow run and streams events as AI SDK UIMessage chunks',\n      tags: ['ai-sdk'],\n      parameters: [\n        {\n          name: 'workflowId',\n          in: 'path',\n          required: true,\n          description: 'The ID of the workflow to stream',\n          schema: { type: 'string' },\n        },\n      ],\n      requestBody: {","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/workflow-route.ts#L194-L230","documentation":"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.","triggerScenarios":"Calling workflowRoute({ path: '/api/workflows/run', ... }) with a path lacking ':workflowId' and without passing the `workflow` option in WorkflowRouteOptions.","commonSituations":"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.","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."],"exampleFix":"// before\nworkflowRoute({ path: '/api/workflow/run', mastra });\n// after\nworkflowRoute({ path: '/api/workflows/:workflowId/run', mastra });\n// or: workflowRoute({ path: '/api/workflow/run', mastra, workflow: myWorkflow });","handlingStrategy":"validation","validationCode":"function assertWorkflowRouteOptions(path: string, opts: { workflow?: unknown }) {\n  if (!opts.workflow && !path.includes('/:workflowId')) {\n    throw new Error('workflowRoute requires a `workflow` option or a path containing :workflowId');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["config","routing","startup-validation"],"backgroundTag":"missing-route-param","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}