mastra-ai/mastra · error · HTTPException

Skill "${identifier}" not found

Error message

Skill "${identifier}" not found

What it means

This HTTP 404 error is thrown when `agent.getSkill(identifier, { requestContext })` returns no skill. The lookup searches the agent's inline skills and workspace skills, using the `?path=` query param for disambiguation when given, otherwise the `:skillName` path param.

Source

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

  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,
        instructions: skill.instructions,
        source: skill.source,
        references: skill.references,
        scripts: skill.scripts,
        assets: skill.assets,
      };
    } catch (error) {
      return handleError(error, 'Error getting agent skill');
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Confirm the exact skill name/path exists on the agent (e.g. via the agent's skills list endpoint) and correct the request.
2. If multiple skills share a name, pass the ?path= query param with the encoded path to disambiguate.
3. Ensure the skill is actually present in the agent's inline skills or workspace and the server was restarted after adding it.

Example fix

// before
GET /api/agents/myAgent/skills/My-Skill   // case mismatch
// after
GET /api/agents/myAgent/skills/my-skill?path=%2Fskills%2Fmy-skill%2FSKILL.md

// list skills for the agent first and check the name
const res = await fetch(`/api/agents/${agentId}/skills`);
const skills = await res.json();
if (!skills.some(s => s.name === skillName)) {
  throw new Error(`Skill "${skillName}" not available on agent ${agentId}`);
}

function hasSkill(skills: { name: string }[], name: string): boolean {
  return skills.some(s => s.name === name);
}

try {
  const res = await fetch(`/api/agents/${agentId}/skills/${encodeURIComponent(skillName)}`);
  if (res.status === 404) throw new Error(`Skill "${skillName}" not found`);
  return await res.json();
} catch (e) { /* offer the user the list of valid skills */ }

When it happens

Trigger: GET /api/agents/:agentId/skills/:skillName where the skill name doesn't match any inline or workspace skill on that agent, or multiple skills share a name and no ?path= disambiguator is provided in a way that resolves one.

Common situations: Typo in skill name; skill file not loaded into the agent's workspace; skill exists on a different agent; name vs path mismatch (the identifier falls back to skillName when ?path= is absent); case sensitivity.

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