mastra-ai/mastra · error · HTTPException

Workflow not found

Error message

Workflow not found

What it means

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.

Source

Thrown at packages/server/src/server/handlers/workflows.ts:155

    if (Object.keys(agents || {}).length) {
      for (const [_, agent] of Object.entries(agents)) {
        try {
          const workflows = await agent.listWorkflows();

          if (workflows[workflowId]) {
            workflow = workflows[workflowId];
            break;
          }
        } catch (error) {
          logger.debug('Error getting workflow from agent', error);
        }
      }
    }
  }

  if (!workflow) {
    throw new HTTPException(404, { message: 'Workflow not found' });
  }

  return { workflow };
}

// ============================================================================
// Route Definitions (new pattern - handlers defined inline with createRoute)
// ============================================================================

export const LIST_WORKFLOWS_ROUTE = createRoute({
  method: 'GET',
  path: '/workflows',
  responseType: 'json',
  queryParamSchema: z.object({
    partial: z.string().optional(),
  }),
  responseSchema: listWorkflowsResponseSchema,
  summary: 'List all workflows',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Confirm the exact workflow id via GET /api/workflows (list all) and correct the caller
2. Ensure the workflow is registered on the Mastra instance the server was started with
3. Restart the server after adding/registering new workflows
4. Check you are hitting the intended environment/deployment

Example fix

// before
await client.getWorkflow('orderProcesing').details();
// after
await client.getWorkflow('orderProcessing').details();

async function workflowExists(client, workflowId) {
  const workflows = await client.listWorkflows();
  return workflows.some(w => w.id === workflowId);
}

function isKnownWorkflow(workflowId: string, known: { id: string }[]): boolean {
  return known.some(w => w.id === workflowId);
}

try {
  const { workflow } = await listWorkflowsFromSystem({ mastra, workflowId });
} catch (e) {
  if (e instanceof HTTPException && e.status === 404) {
    const available = await mastra.listWorkflows();
    throw new Error(`Workflow "${workflowId}" not found. Available: ${available.map(w => w.id).join(', ')}`);
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Conversation ${conversationId} was not found
• Model "${modelId}" is not available. Available models: ${ids
• ACP connection is not initialized
• Model "${this.options.model}" is not available. Available mo
• ClaudeSDKAgent resumeData must include either sessionId or c

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/fb9e1ee41d65c984. Report an issue: GitHub.