mastra-ai/mastra · error · HTTPException

Workflow "${body.workflowId}" not found

Error message

Workflow "${body.workflowId}" not found

What it means

When creating a schedule targeting a workflow, the handler validates the workflow exists via mastra.getWorkflowById(body.workflowId); a throw is translated into HTTP 404 'Workflow "<id>" not found' instead of a 500.

Source

Thrown at packages/server/src/server/handlers/schedules.ts:148

  method: 'POST',
  path: '/schedules',
  responseType: 'json' as const,
  bodySchema: createScheduleBodySchema,
  responseSchema: scheduleSchema,
  summary: 'Create a schedule',
  description:
    'Creates a new schedule. Pass `agentId` (plus `prompt`) to schedule an agent, or `workflowId` (plus optional `inputData`) to schedule a workflow. Agent schedules get a random `agent_<uuid>` id, workflow schedules a random `schedule_<uuid>` id; pass `id` for a stable slug instead.',
  tags: ['Schedules'],
  requiresAuth: true,
  handler: async ({ mastra, ...body }) => {
    // getAgentById / getWorkflowById throw a MastraError (status 404) when the
    // target is unknown; translate that into a clean HTTP 404 instead of
    // letting it surface as 500.
    if ('workflowId' in body && body.workflowId) {
      try {
        mastra.getWorkflowById(body.workflowId);
      } catch {
        throw new HTTPException(404, { message: `Workflow "${body.workflowId}" not found` });
      }
      return await mastra.schedules.create({
        workflowId: body.workflowId,
        cron: body.cron,
        ...(body.id ? { id: body.id } : {}),
        ...(body.timezone ? { timezone: body.timezone } : {}),
        ...(body.inputData !== undefined ? { inputData: body.inputData } : {}),
        ...(body.initialState !== undefined ? { initialState: body.initialState } : {}),
        ...(body.requestContext ? { requestContext: body.requestContext } : {}),
        ...(body.metadata ? { metadata: body.metadata } : {}),
      });
    }
    const agentBody = body as Extract<typeof body, { agentId: string }>;
    try {
      mastra.getAgentById(agentBody.agentId);
    } catch {
      throw new HTTPException(404, { message: `Agent "${agentBody.agentId}" not found` });
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use the exact registered id the workflow was created with in new Workflow({ id: ... }).
2. Confirm the workflow module is imported and included in the Mastra constructor's workflows map.
3. Verify with mastra.getWorkflowById(id) locally before calling the API.

Example fix

// before
POST /api/schedules { "workflowId": "dataPipeline", ... }  // registered as 'data-pipeline'
// after
POST /api/schedules { "workflowId": "data-pipeline", ... }

const registered = mastra.getWorkflowById(workflowId); // throws if missing
// or client-side: keep workflowIds from the Mastra config, not export names
if (!knownWorkflowIds.includes(workflowId)) {
  throw new Error(`Workflow "${workflowId}" is not registered`);
}

try {
  await client.createSchedule({ workflowId, cron });
} catch (e) {
  if (isHttpError(e, 404) && /not found/.test(e.message)) {
    throw new Error(`Register workflow '${workflowId}' on the Mastra instance first`);
  }
  throw e;
}

When it happens

Trigger: POST /api/schedules with body.workflowId set to an id that mastra.getWorkflowById cannot resolve (workflow not registered on the Mastra instance).

Common situations: Workflow registered with a different id/name than the one sent; workflows module not imported/registered into the Mastra instance; id casing mismatch; referring to a workflow by its export name instead of its registered id.

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

• Agent "${agentBody.agentId}" not found
• @mastra/livekit: `workflowInput` is required when `workflow`
• save-workflow requires a Mastra context.
• AGENT_FS_ROUTING_SUBAGENT_SCHEDULES_UNSUPPORTED
• SCHEDULES_AMBIGUOUS_MODE

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