{"record":{"id":"cc0160d63046099f","repo":"mastra-ai/mastra","slug":"workflow-id-is-required","errorCode":null,"errorMessage":"Workflow ID is required","messagePattern":"Workflow ID is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client-sdks/ai-sdk/src/workflow-route.ts","lineNumber":279,"sourceCode":"      const params = (await c.req.json()) as WorkflowStreamHandlerParams;\n      const mastra = c.get('mastra');\n      const contextRequestContext = (c as any).get('requestContext') as RequestContext | undefined;\n\n      let workflowToUse: string | undefined = workflow;\n      if (!workflow) {\n        const workflowId = c.req.param('workflowId');\n        workflowToUse = workflowId;\n      }\n\n      if (c.req.param('workflowId') && workflow) {\n        mastra\n          .getLogger()\n          ?.warn(\n            `Fixed workflow ID was set together with a workflowId path parameter. This can lead to unexpected behavior.`,\n          );\n      }\n      if (!workflowToUse) {\n        throw new Error('Workflow ID is required');\n      }\n\n      const handlerOptions = {\n        mastra,\n        workflowId: workflowToUse,\n        params: {\n          ...params,\n          requestContext: contextRequestContext || params.requestContext,\n        },\n        includeTextStreamParts,\n        sendReasoning,\n        sendSources,\n      };\n\n      if (version === 'v7') {\n        const uiMessageStream = await handleWorkflowStream({\n          ...handlerOptions,\n          version: 'v7',","sourceCodeStart":261,"sourceCodeEnd":297,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/client-sdks/ai-sdk/src/workflow-route.ts#L261-L297","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the request URL includes the workflow ID in the :workflowId segment.","Re-register the route with a fixed `workflow` option if the path is static.","Check server route registration logs; also note the warning about setting both a fixed workflow and a path param, which can conflict."],"exampleFix":"// before\nawait fetch('/api/workflow/run', { method: 'POST', ... });\n// after\nawait fetch('/api/workflows/myWorkflowId/run', { method: 'POST', ... });","handlingStrategy":"validation","validationCode":"// client side\nconst workflowId = extractParam(url, 'workflowId');\nif (!workflowId) throw new Error('workflowId path param is required for this endpoint');","typeGuard":null,"tryCatchPattern":"try {\n  await streamWorkflow(url);\n} catch (e) {\n  if (e instanceof Error && e.message === 'Workflow ID is required') {\n    // fix request URL / route registration\n  }\n  throw e;\n}","preventionTips":["Always build workflow URLs from a helper that interpolates the workflow ID.","Avoid registering a fixed workflow together with a :workflowId path param (conflicting resolution).","Test each registered route with a real POST before deploying."],"tags":["routing","request-time","workflow"],"backgroundTag":"missing-route-param","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}