{"record":{"id":"dccaa4a841b21e81","repo":"mastra-ai/mastra","slug":"runid-required-to-start-run","errorCode":null,"errorMessage":"runId required to start run","messagePattern":"runId required to start run","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/workflows.ts","lineNumber":718,"sourceCode":"  responseType: 'json',\n  pathParamSchema: workflowIdPathParams,\n  queryParamSchema: runIdSchema,\n  bodySchema: startAsyncWorkflowBodySchema,\n  responseSchema: workflowControlResponseSchema,\n  summary: 'Start specific workflow run',\n  description: 'Starts execution of a specific workflow run by ID',\n  tags: ['Workflows'],\n  requiresAuth: true,\n  handler: async ({ mastra, workflowId, runId, requestContext, ...params }) => {\n    try {\n      const effectiveResourceId = getEffectiveResourceId(requestContext, undefined);\n\n      if (!workflowId) {\n        throw new HTTPException(400, { message: 'Workflow ID is required' });\n      }\n\n      if (!runId) {\n        throw new HTTPException(400, { message: 'runId required to start run' });\n      }\n\n      const { workflow } = await listWorkflowsFromSystem({ mastra, workflowId });\n\n      if (!workflow) {\n        throw new HTTPException(404, { message: 'Workflow not found' });\n      }\n\n      const run = await workflow.getWorkflowRunById(runId);\n\n      if (!run) {\n        throw new HTTPException(404, { message: 'Workflow run not found' });\n      }\n\n      await validateRunOwnership(run, effectiveResourceId);\n\n      const _run = await workflow.createRun({ runId, resourceId: run.resourceId });\n      // Fire-and-forget: attach .catch so a rejected start (e.g. invalid input","sourceCodeStart":700,"sourceCodeEnd":736,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workflows.ts#L700-L736","documentation":"Thrown by the start-run handler when `runId` is missing after workflowId validation. Starting a run by id requires the caller-supplied runId, so the server returns HTTP 400 before resolving the workflow.","triggerScenarios":"Call to the start-run endpoint without runId in path/body; passing the workflowId twice instead of workflowId+runId; runId variable lost between creating the run and starting it (e.g. across processes).","commonSituations":"Distributed setups where one service creates the run and another starts it but forgets to pass the id; SDK misuse passing an options object as the runId; empty string from an untrimmed input field.","solutions":["Pass the runId obtained from `workflow.createRun({ runId })` or your own generated id.","Persist the runId where the starting service can read it (queue, DB, shared store).","Trim/validate the runId input client-side before calling."],"exampleFix":"// before\nawait client.startRun({ workflowId, runId: undefined })\n// after\nconst { runId } = await workflow.createRun();\nawait client.startRun({ workflowId, runId })","handlingStrategy":"validation","validationCode":"if (!runId) {\n  throw new TypeError('runId is required to start a run; get one from workflow.createRun()');\n}\nawait client.startRun({ workflowId, runId });","typeGuard":"function hasRunId(x: { runId?: string }): x is { runId: string } {\n  return typeof x.runId === 'string' && x.runId.trim().length > 0;\n}","tryCatchPattern":"try {\n  await client.startRun({ workflowId, runId });\n} catch (e) {\n  if (e instanceof MastraClientError && e.status === 400 && /runId/.test(e.message)) {\n    const newRun = await client.createRun(workflowId);\n    return client.startRun({ workflowId, runId: newRun.runId });\n  }\n  throw e;\n}","preventionTips":["Create and start the run in the same code path so runId never crosses a serialization boundary.","If creation and start must be split, pass runId through durable state, not memory.","Trim user-supplied runIds and reject empty strings before calling the API."],"tags":["http-400","validation","missing-parameter","workflow-run"],"backgroundTag":"missing-required-param","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}