mastra-ai/mastra · error · HTTPException

Could not find skill "${skillName}" in ${owner}/${repo}.

Error message

Could not find skill "${skillName}" in ${owner}/${repo}.

What it means

The install-skill handler fetches the skill's files from the upstream registry via fetchSkillFiles(owner, repo, skillName) and throws a 404 HTTPException when the fetch returns nothing or an empty file list. This means no skill matching skillName exists in the given owner/repo on the registry (or the registry returned no content).

Source

Thrown at packages/server/src/server/handlers/builder-registry.ts:346

  requiresAuth: true,
  requiresPermission: 'stored-skills:write',
  handler: async ({ mastra, requestContext, registryId, owner, repo, skillName, visibility: bodyVisibility }) => {
    try {
      await requireEnabledRegistry(mastra, registryId);

      const storage = mastra.getStorage();
      if (!storage) {
        throw new HTTPException(500, { message: 'Storage is not configured' });
      }
      const skillStore = await storage.getStore('skills');
      if (!skillStore) {
        throw new HTTPException(500, { message: 'Skills storage domain is not available' });
      }

      // Pull files from the registry
      const result = await fetchSkillFiles(owner, repo, skillName);
      if (!result || result.files.length === 0) {
        throw new HTTPException(404, {
          message: `Could not find skill "${skillName}" in ${owner}/${repo}.`,
        });
      }

      const safeSkillId = assertSafeSkillName(result.skillId);
      const files = buildFileTree(result.files);

      // Parse SKILL.md frontmatter into structured fields. Splitting
      // frontmatter (name/description) from the markdown body keeps the
      // body as the agent-facing `instructions` instead of polluting it
      // with raw YAML metadata. SKILL.md missing or unparseable simply
      // yields a null snapshot — registry-provided values then fill in.
      const snapshot = parseSkillSnapshot(result.files);

      const resolvedName = snapshot?.name ?? safeSkillId;
      const description = snapshot?.description ?? `Imported from ${owner}/${repo}`;
      const id = toSlug(resolvedName) || safeSkillId;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the skill exists in owner/repo on the registry (browse the repo or registry search endpoint) and match the exact skillName.
2. Check owner/repo spelling and casing exactly as the registry indexes them.
3. Retry if the registry may have transient issues; empty results from an outage look like not-found.
4. If the skill was recently published, wait for registry indexing before installing.

Example fix

// before
await install({ registryId, owner: 'acme', repo: 'skills', skillName: 'code-review ' }); // trailing space

// after
const search = await searchRegistry(registryId, 'code-review');
await install({ registryId, owner: search.owner, repo: search.repo, skillName: search.name });

const results = await registrySearch(registryId, skillName);
const match = results.find(r => r.name === skillName && r.owner === owner && r.repo === repo);
if (!match) throw new Error(`Skill "${skillName}" not found in ${owner}/${repo}; search first`);

try {
  await installSkill({ registryId, owner, repo, skillName });
} catch (e) {
  if (e.status === 404 && e.message.startsWith('Could not find skill')) {
    // offer registry search UI to pick the correct skill
  } else throw e;
}

When it happens

Trigger: POSTing the install route with a skillName that does not exist in owner/repo; a repo path that exists but contains no skill files; a registry outage or partial response causing an empty result; wrong owner/repo casing or path.

Common situations: Typo in the skill name; skill renamed or removed upstream; browsing a repo root that has skills in a subdirectory; registry indexing lag for newly published skills.

Related errors

• Registry not found
• Could not derive skill ID from registry skill metadata.
• Skill with id "${id}" already exists.
• No workspace with skills configured
• Skill "${identifier}" not found

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