{"record":{"id":"f478ddeaf47eee3b","repo":"mastra-ai/mastra","slug":"workflow-id-is-required-f478dd","errorCode":null,"errorMessage":"Workflow ID is required","messagePattern":"Workflow ID is required","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/workflows.ts","lineNumber":118,"sourceCode":"      reader.releaseLock();\n      activeRunStreamCachers.delete(runId);\n    }\n  })();\n\n  return toClient;\n}\n\nexport interface WorkflowContext extends Context {\n  workflowId?: string;\n  runId?: string;\n  requestContext?: RequestContext;\n}\n\nasync function listWorkflowsFromSystem({ mastra, workflowId }: WorkflowContext) {\n  const logger = mastra.getLogger();\n\n  if (!workflowId) {\n    throw new HTTPException(400, { message: 'Workflow ID is required' });\n  }\n\n  let workflow;\n\n  // First check registry for temporary workflows\n  workflow = WorkflowRegistry.getWorkflow(workflowId);\n\n  if (!workflow) {\n    try {\n      workflow = mastra.getWorkflowById(workflowId);\n    } catch (error) {\n      logger.debug('Error getting workflow, searching agents for workflow', error);\n    }\n  }\n\n  if (!workflow) {\n    logger.debug('Workflow not found, searching agents for workflow', { workflowId });\n    const agents = mastra.listAgents();","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workflows.ts#L100-L136","documentation":"listWorkflowsFromSystem resolves a workflow either from the temporary-workflow registry or from the Mastra instance's storage, and it refuses to run without a `workflowId`. The 400 'Workflow ID is required' is thrown before any lookup when workflowId is falsy. It is an internal helper shared by several workflow route handlers, so the error surfaces through whichever endpoint omitted the ID.","triggerScenarios":"Calling any workflow route that resolves to listWorkflowsFromSystem (e.g. GET workflow details/runs) without the workflowId path parameter; a client passing undefined workflowId to listWorkflows on aMastra instance.","commonSituations":"Manually constructed URLs missing the workflow id segment; programmatic use of a Mastra instance where the workflow id variable is undefined because the workflow was never registered under the expected name.","solutions":["Pass the workflowId in the request path or call arguments","Verify the workflow id matches the id used at new Workflow()/register time","If listing all workflows, use the workflows list endpoint that does not require a single id"],"exampleFix":"// before\nconst { workflow } = await listWorkflowsFromSystem({ mastra, workflowId: undefined });\n// after\nconst { workflow } = await listWorkflowsFromSystem({ mastra, workflowId: 'myWorkflowId' });","handlingStrategy":"validation","validationCode":"async function safeGetWorkflow(mastra, workflowId) {\n  if (!workflowId) throw new TypeError('workflowId is required');\n  return listWorkflowsFromSystem({ mastra, workflowId });\n}","typeGuard":"function hasWorkflowId(args): args is WorkflowContext & { workflowId: string } {\n  return typeof (args as any)?.workflowId === 'string' && (args as any).workflowId.length > 0;\n}","tryCatchPattern":"try {\n  const { workflow } = await listWorkflowsFromSystem({ mastra, workflowId });\n} catch (e) {\n  if (e instanceof HTTPException && e.status === 400) {\n    return { error: 'workflowId is required' };\n  }\n  throw e;\n}","preventionTips":["Centralize workflow ids in constants/enums instead of inline strings","Type route params so workflowId is non-optional at compile time","Use the all-workflows list endpoint when no specific id is needed","Log the id at call sites feeding dynamic workflow lookups"],"tags":["http-400","workflows","missing-parameter","server-api"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}