{"record":{"id":"0634f3d0a1ac6d66","repo":"mastra-ai/mastra","slug":"run-id-is-required-0634f3","errorCode":null,"errorMessage":"Run ID is required","messagePattern":"Run ID is required","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/workflows.ts","lineNumber":437,"sourceCode":"  responseType: 'json',\n  pathParamSchema: workflowRunPathParams,\n  queryParamSchema: workflowRunResultQuerySchema,\n  responseSchema: workflowRunResultSchema,\n  summary: 'Get workflow run by ID',\n  description:\n    'Returns a workflow run with metadata and processed execution state. Use the fields query parameter to reduce payload size by requesting only specific fields (e.g., ?fields=status,result,metadata)',\n  tags: ['Workflows'],\n  requiresAuth: true,\n  handler: async ({ mastra, workflowId, runId, fields, withNestedWorkflows, requestContext }) => {\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: 'Run ID is required' });\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      // Parse fields parameter (comma-separated string)\n      const fieldList = fields ? (fields.split(',').map((f: string) => f.trim()) as WorkflowStateField[]) : undefined;\n\n      const run = await workflow.getWorkflowRunById(runId, {\n        withNestedWorkflows: withNestedWorkflows !== 'false', // Default to true unless explicitly 'false'\n        fields: fieldList,\n      });\n\n      if (!run) {\n        throw new HTTPException(404, { message: 'Workflow run not found' });","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workflows.ts#L419-L455","documentation":"Immediately after the workflowId check, the getWorkflowRunById handler validates `runId` and throws 400 'Run ID is required' when it is falsy. A workflowId alone cannot identify a run; the pair (workflowId, runId) is required to fetch the run's snapshot and execution results from storage.","triggerScenarios":"GET /api/workflows/:workflowId/runs/ with an empty run id; calling getWorkflowRun(undefined); a run list rendering before the selected runId state is set; route params where :runId failed to match (optional segment).","commonSituations":"Auto-starting detail views before a run is selected; regex route changes making runId optional; run ids lost when rehydrating UI state from storage or links shared without the run segment.","solutions":["Provide the runId in the request path: GET /api/workflows/:workflowId/runs/:runId","Gate the detail fetch on runId being truthy in the consuming UI","Persist the full (workflowId, runId) pair in links and saved state"],"exampleFix":"// before\nuseEffect(() => { fetchRun(workflowId, runId); }, [workflowId]);\n// after\nuseEffect(() => { if (workflowId && runId) fetchRun(workflowId, runId); }, [workflowId, runId]);","handlingStrategy":"validation","validationCode":"function canFetchRun(state) {\n  return Boolean(state?.workflowId) && Boolean(state?.runId);\n}\n// usage\nif (canFetchRun(state)) fetchWorkflowRun(client, state.workflowId, state.runId);","typeGuard":"function hasRunId(v): v is { workflowId: string; runId: string } {\n  return typeof (v as any)?.runId === 'string' && (v as any).runId.length > 0;\n}","tryCatchPattern":"try {\n  return await getWorkflowRunById({ mastra, workflowId, runId });\n} catch (e) {\n  if (e?.status === 400 && /run id is required/i.test(e?.message ?? '')) {\n    return { error: 'Select a run before fetching details' };\n  }\n  throw e;\n}","preventionTips":["Gate run-detail fetches/effects on runId being truthy","Make runId a required route param in client-side routers","Disable run-detail UI until a run is selected","Validate shared links contain both workflowId and runId before navigating"],"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-30T08:17:16.595Z"}