{"record":{"id":"ace30ec8aceb87d4","repo":"mastra-ai/mastra","slug":"runid-required-to-restart-workflow","errorCode":null,"errorMessage":"runId required to restart workflow","messagePattern":"runId required to restart workflow","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/workflows.ts","lineNumber":994,"sourceCode":"  responseType: 'json',\n  pathParamSchema: workflowIdPathParams,\n  queryParamSchema: runIdSchema,\n  bodySchema: restartBodySchema,\n  responseSchema: workflowExecutionResultSchema,\n  summary: 'Restart workflow asynchronously',\n  description: 'Restarts an active workflow execution asynchronously',\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 restart workflow' });\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      const result = await _run.restart({ ...params, requestContext });","sourceCodeStart":976,"sourceCodeEnd":1012,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workflows.ts#L976-L1012","documentation":"The POST /api/workflows/:workflowId/restart-run (async) handler requires a runId path/query parameter identifying which workflow run to restart. The server validates required parameters before doing any storage lookup and throws HTTPException(400) when runId is missing. This is a client-side request-shape error, not a server fault.","triggerScenarios":"Calling the restart-run async endpoint without supplying runId in the request (missing path param or query string), e.g. POST /workflows/myWorkflow/restart-run with only workflowId present.","commonSituations":"Client SDK or fetch call built from a template where the runId variable was undefined/null; UI code that lists workflows but forgot to pass the selected run's id; copying a restart-all route pattern for the per-run route.","solutions":["Include the runId parameter in the request path/query, e.g. POST /api/workflows/:workflowId/restart-run/:runId.","Fetch the run id first via the workflow runs list endpoint if you don't have it.","Coerce/trim the value: an empty string runId will also fail this check, so ensure the client sends a non-empty id."],"exampleFix":"// before\nawait fetch(`/api/workflows/${workflowId}/restart-run`);\n// after\nawait fetch(`/api/workflows/${workflowId}/restart-run/${runId}`);","handlingStrategy":"validation","validationCode":"if (!runId || typeof runId !== 'string' || runId.trim() === '') {\n  throw new Error('runId is required before calling restart-run');\n}","typeGuard":"function hasRunId(v: unknown): v is string {\n  return typeof v === 'string' && v.trim().length > 0;\n}","tryCatchPattern":"try {\n  await restartRun(workflowId, runId);\n} catch (e) {\n  if (isHttpError(e, 400) && /runId required/.test(e.message)) {\n    throw new Error('Client bug: runId must be supplied to restart a workflow run');\n  }\n  throw e;\n}","preventionTips":["Build endpoint URLs from typed helpers that require runId as a non-empty string parameter.","Validate all route params client-side before issuing the request.","Cover the restart call in unit tests with both present and absent runId."],"tags":["http-400","missing-parameter","workflow","server-api"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}