mastra-ai/mastra · error · HTTPException

Skill "${identifier}" not found

Error message

Skill "${identifier}" not found

What it means

The get-skill-details route (GET /workspaces/:workspaceId/skills/:skillName) throws this 404 after the skills provider refreshes and skills.get(identifier) returns null — the skill (addressed by name, or by the ?path= query param when disambiguating) does not exist in the configured skills set.

Source

Thrown at packages/server/src/server/handlers/workspace.ts:973

      if (!skillName) {
        throw new HTTPException(400, { message: 'Skill name is required' });
      }

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

      const skills = await getSkillsById(mastra, workspaceId);
      if (!skills) {
        throw new HTTPException(404, { message: 'No workspace with skills configured' });
      }

      // Refresh skills with request context (handles dynamic skill resolvers)
      await skills.maybeRefresh({ requestContext });

      const skill = await skills.get(identifier);
      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 handleWorkspaceError(error, 'Error getting skill');
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. List skills via GET /workspaces/:id/skills and use an exact returned name (or its path as ?path=).
2. Verify the skill's SKILL.md exists under the workspace's configured skills globs.
3. Install the skill (e.g. via skills.sh) before requesting it.
4. Check case and URL-encoding of skillName/path; correct the identifier.

Example fix

// before
await fetch(`/api/workspaces/ws1/skills/code-reveiwer`);
// after
const { skills } = await fetch(`/api/workspaces/ws1/skills`).then(r => r.json());
await fetch(`/api/workspaces/ws1/skills/${encodeURIComponent(skills[0].name)}`);

// Ensure the skill exists before fetching details
const { skills } = await fetch(`/api/workspaces/${wsId}/skills`).then(r => r.json());
const known = skills.some(s => s.name === skillName || s.path === disambiguationPath);
if (!known) throw new Error(`Skill ${skillName} is not installed in workspace ${wsId}`);

function skillExists(list: { name: string; path: string }[], identifier: string): boolean {
  return list.some(s => s.name === identifier || s.path === identifier);
}

try {
  const skill = await getSkill(wsId, identifier);
} catch (e) {
  if (isHTTPException(e, 404) && /Skill ".*" not found/.test(e.message)) {
    // refresh the skill list / install the skill, then retry once
  } else throw e;
}

When it happens

Trigger: Requesting a skillName that isn't installed/discovered; passing a ?path= disambiguation value that doesn't match a discovered skill path; case-sensitivity mismatch; skill directory not yet scanned (or removed) when the request arrives; dynamic skill resolver returning nothing for this context.

Common situations: Typo'd or renamed skill names; skills installed under a different glob than the server's configured one; requesting before skills.sh install completed; ?path= pointing to a skill in another workspace root; stale client caches referencing deleted skills.

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

• Could not find skill "${skillName}" in ${owner}/${repo}.
• Skill "${skillName}" not found at ${skillPath}
• No workspace with skills configured
• Could not find skill "${skillName}" for ${owner}/${repo}
• Workspace not found

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