mastra-ai/mastra · error · HTTPException

Agent "${agentBody.agentId}" not found

Error message

Agent "${agentBody.agentId}" not found

What it means

When creating a schedule targeting an agent, the handler validates the agent exists via mastra.getAgentById(agentBody.agentId); failure is translated to HTTP 404 'Agent "<id>" not found'.

Source

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

      } 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` });
    }
    return await mastra.schedules.create({
      agentId: agentBody.agentId,
      cron: agentBody.cron,
      prompt: agentBody.prompt,
      ...(agentBody.id ? { id: agentBody.id } : {}),
      ...(agentBody.name ? { name: agentBody.name } : {}),
      ...(agentBody.timezone ? { timezone: agentBody.timezone } : {}),
      ...(agentBody.threadId ? { threadId: agentBody.threadId } : {}),
      ...(agentBody.resourceId ? { resourceId: agentBody.resourceId } : {}),
      ...(agentBody.signalType ? { signalType: agentBody.signalType } : {}),
      ...(agentBody.tagName ? { tagName: agentBody.tagName } : {}),
      ...(agentBody.attributes ? { attributes: agentBody.attributes } : {}),
      ...(agentBody.ifActive ? { ifActive: agentBody.ifActive } : {}),
      ...(agentBody.ifIdle ? { ifIdle: agentBody.ifIdle } : {}),
      ...(agentBody.providerOptions ? { providerOptions: agentBody.providerOptions } : {}),
      ...(agentBody.metadata ? { metadata: agentBody.metadata } : {}),
    });

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Use the agent's registered id from new Agent({ id/name: ... }) exactly.
  2. Confirm the agent is included in the Mastra constructor's agents map.
  3. Validate with mastra.getAgentById(id) locally before calling the create route.

Example fix

// before
POST /api/schedules { "agentId": "Support Agent", ... }  // registered id 'support-agent'
// after
POST /api/schedules { "agentId": "support-agent", ... }
Defensive patterns

Strategy: validation

Validate before calling

const registered = mastra.getAgentById(agentId); // throws if missing
// or client-side:
if (!knownAgentIds.includes(agentId)) {
  throw new Error(`Agent "${agentId}" is not registered`);
}

Try / catch

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

Prevention

When it happens

Trigger: POST /api/schedules with body.agentId set to an id not registered on the Mastra instance.

Common situations: Agent registered under a different id than the name used in the request; agents module not wired into the Mastra instance; case/space mismatch in the 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

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