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

HTTPException 404 thrown after fetchSkillFiles returns null or a response with an empty files array, meaning the skill could not be located (or has no files) in the given owner/repo on skills.sh. Distinct from 3303: this is the multi-file install path.

Source

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

      requireWorkspaceV1Support();

      const workspace = await getWorkspaceById(mastra, workspaceId);
      if (!workspace) {
        throw new HTTPException(404, { message: 'Workspace not found' });
      }

      if (!workspace.filesystem) {
        throw new HTTPException(400, { message: 'Workspace filesystem not available' });
      }

      if (workspace.filesystem.readOnly) {
        throw new HTTPException(403, { message: 'Workspace is read-only' });
      }

      // Fetch skill files from the Skills API
      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}.`,
        });
      }

      // Validate skill name to prevent path traversal
      const safeSkillId = assertSafeSkillName(result.skillId);
      const installPath = buildSkillInstallPath(workspace.filesystem, safeSkillId, mount);

      // Ensure the skills directory exists
      try {
        await workspace.filesystem.mkdir(installPath, { recursive: true });
      } catch {
        // Directory might already exist
      }

      // Write all files to the workspace
      let filesWritten = 0;
      for (const file of result.files) {

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Verify the skill exists with files at skills.sh for that exact owner/repo slug.
  2. Check the repo is public/accessible to the upstream API.
  3. Retry shortly after publishing if the skill is new (indexing delay), or fall back to installing files fetched directly from the repository.

Example fix

// before
await installSkill({ workspaceId, owner: 'acme', repo: 'widgets', skillName: 'deploy' });
// after
await installSkill({ workspaceId, owner: 'acme', repo: 'widget-skills', skillName: 'deploy' }); // correct repo
Defensive patterns

Strategy: try-catch

Validate before calling

// Verify the skill resolves (non-empty file list) before installing
const listing = await fetchSkillFiles(owner, repo, skillName).catch(() => null);
if (!listing || listing.files.length === 0) throw new Error(`Skill ${skillName} not found in ${owner}/${repo}`);

Type guard

function isSkillListing(r: unknown): r is { skillId: string; files: unknown[] } {
  const o = r as any;
  return !!o && typeof o.skillId === 'string' && Array.isArray(o.files);
}

Try / catch

try {
  await installSkill({ workspaceId, owner, repo, skillName });
} catch (e) {
  if (new RegExp(`Could not find skill "${skillName}"`).test(String(e))) {
    console.warn('Skill not found; verify the slug on skills.sh.');
    return { installed: false };
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling the workspace install-skill route with an owner/repo/skillName whose files listing yields no files — wrong slug, unpublished skill, or private repo.

Common situations: Typos in skill or repo names; skill moved to another repo; skills.sh indexing lag for freshly published skills; repo made private after the skill was referenced.

Related errors

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