{"record":{"id":"fb9e1ee41d65c984","repo":"mastra-ai/mastra","slug":"workflow-not-found","errorCode":null,"errorMessage":"Workflow not found","messagePattern":"Workflow not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/workflows.ts","lineNumber":155,"sourceCode":"\n    if (Object.keys(agents || {}).length) {\n      for (const [_, agent] of Object.entries(agents)) {\n        try {\n          const workflows = await agent.listWorkflows();\n\n          if (workflows[workflowId]) {\n            workflow = workflows[workflowId];\n            break;\n          }\n        } catch (error) {\n          logger.debug('Error getting workflow from agent', error);\n        }\n      }\n    }\n  }\n\n  if (!workflow) {\n    throw new HTTPException(404, { message: 'Workflow not found' });\n  }\n\n  return { workflow };\n}\n\n// ============================================================================\n// Route Definitions (new pattern - handlers defined inline with createRoute)\n// ============================================================================\n\nexport const LIST_WORKFLOWS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/workflows',\n  responseType: 'json',\n  queryParamSchema: z.object({\n    partial: z.string().optional(),\n  }),\n  responseSchema: listWorkflowsResponseSchema,\n  summary: 'List all workflows',","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workflows.ts#L137-L173","documentation":"After checking both the temporary-workflow registry and the Mastra instance's registered workflows, listWorkflowsFromSystem throws 404 'Workflow not found' when no workflow matches the supplied workflowId. Unlike the 400 guard, this means the request was well-formed but the identifier does not resolve to any known workflow in this server process.","triggerScenarios":"GET /api/workflows/:workflowId with an id that was never registered; the workflow exists in code but the server was started from a different Mastra instance/entrypoint that never registered it; a temporary workflow was requested after the registry entry was cleared.","commonSituations":"Typos or casing mismatches in workflow ids; pointing the client at a different environment (staging vs prod) where the workflow isn't deployed; renaming a workflow without updating callers; hot-reload dropping unregistered temp workflows.","solutions":["Confirm the exact workflow id via GET /api/workflows (list all) and correct the caller","Ensure the workflow is registered on the Mastra instance the server was started with","Restart the server after adding/registering new workflows","Check you are hitting the intended environment/deployment"],"exampleFix":"// before\nawait client.getWorkflow('orderProcesing').details();\n// after\nawait client.getWorkflow('orderProcessing').details();","handlingStrategy":"try-catch","validationCode":"async function workflowExists(client, workflowId) {\n  const workflows = await client.listWorkflows();\n  return workflows.some(w => w.id === workflowId);\n}","typeGuard":"function isKnownWorkflow(workflowId: string, known: { id: string }[]): boolean {\n  return known.some(w => w.id === workflowId);\n}","tryCatchPattern":"try {\n  const { workflow } = await listWorkflowsFromSystem({ mastra, workflowId });\n} catch (e) {\n  if (e instanceof HTTPException && e.status === 404) {\n    const available = await mastra.listWorkflows();\n    throw new Error(`Workflow \"${workflowId}\" not found. Available: ${available.map(w => w.id).join(', ')}`);\n  }\n  throw e;\n}","preventionTips":["Keep workflow ids in one source of truth shared by registration and callers","Fetch the workflow list to verify ids before deep-linking","Handle 404 gracefully in UIs (show 'workflow unavailable')","Re-verify ids after renames or cross-environment deploys"],"tags":["http-404","workflows","not-found","server-api"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}