mastra-ai/mastra · error · HTTPException

Agent not found

Error message

Agent not found

What it means

This HTTP 404 error is thrown when the skills detail route cannot resolve the `:agentId` path parameter to a registered agent: `mastra.getAgentById(agentId)` returns null/undefined. It means the agent does not exist in the current Mastra instance's registry.

Source

Thrown at packages/server/src/server/handlers/agents.ts:3620

// ============================================================================
// Agent Skill Routes
// ============================================================================

export const GET_AGENT_SKILL_ROUTE = createRoute({
  method: 'GET',
  path: '/agents/:agentId/skills/:skillName',
  responseType: 'json',
  pathParamSchema: agentSkillPathParams,
  queryParamSchema: skillDisambiguationQuerySchema,
  responseSchema: getAgentSkillResponseSchema,
  summary: 'Get agent skill',
  description: 'Returns details for a specific skill available to the agent (inline or workspace)',
  tags: ['Agents', 'Skills'],
  handler: async ({ mastra, agentId, skillName, path, requestContext }) => {
    try {
      const agent = agentId ? mastra.getAgentById(agentId) : null;
      if (!agent) {
        throw new HTTPException(404, { message: 'Agent not found' });
      }

      // Use the optional ?path= query param for disambiguation, otherwise fall back to name
      const identifier = path ? decodeURIComponent(path) : skillName;

      // Get the skill from the agent (searches both inline and workspace skills)
      const skill = await agent.getSkill(identifier, { requestContext });
      if (!skill) {
        throw new HTTPException(404, { message: `Skill "${identifier}" not found` });
      }

      return {
        name: skill.name,
        description: skill.description,
        license: skill.license,
        compatibility: skill.compatibility,
        metadata: skill.metadata,
        path: skill.path,

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Verify the agentId exists: call GET /api/agents and confirm the ID is listed.
  2. Register the agent on the Mastra instance passed to the server (agents map in Mastra constructor or setLogger-adjacent registration).
  3. Check for typos/case differences and correct URL-encoding of the agentId in the request path.

Example fix

// before
new Mastra({ /* agents not registered */ });
// after
new Mastra({ agents: { myAgent } });
// request: /api/agents/myAgent/skills/my-skill
Defensive patterns

Strategy: validation

Validate before calling

// resolve the agent id against the registry before calling the skills route
const agents = await (await fetch('/api/agents')).json();
if (!agents.some(a => a.id === agentId)) {
  throw new Error(`Agent "${agentId}" is not registered on this server`);
}

Type guard

function isRegisteredAgent(agentId: string, agents: { id: string }[]): boolean {
  return agents.some(a => a.id === agentId);
}

Try / catch

try {
  const res = await fetch(`/api/agents/${agentId}/skills/${skillName}`);
  if (res.status === 404) throw new Error(`Agent "${agentId}" not found`);
  return await res.json();
} catch (e) { /* surface a friendly 'agent not found' message */ }

Prevention

When it happens

Trigger: GET /api/agents/:agentId/skills/:skillName (or with ?path=) where agentId is not registered via mastra.getAgentById — wrong ID, agent not registered on the Mastra instance, or typo/case mismatch.

Common situations: Agent renamed or removed from mastra.getAgent registration; server instance differs from the one the client was built against; agentId casing or URL-encoding issues; dynamic agents not yet registered when the request arrives.

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/5c34cc8edf955099. Report an issue: GitHub.