mastra-ai/mastra · warning · HTTPException

Stored skill with id ${storedSkillId} not found

Error message

Stored skill with id ${storedSkillId} not found

What it means

This 404 is thrown by the GET stored-skill handler after `skillStore.getByIdResolved(storedSkillId)` returns null, meaning no stored skill record (plus resolvable version config) exists for the requested ID in the skills storage domain. The library throws it to signal a missing resource before scope/read-access checks run. It is a normal lookup miss, not an infrastructure failure.

Source

Thrown at packages/server/src/server/handlers/stored-skills.ts:270

  tags: ['Stored Skills'],
  requiresAuth: true,
  handler: async ({ mastra, requestContext, storedSkillId }) => {
    try {
      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' });
      }

      const skill = await skillStore.getByIdResolved(storedSkillId);

      if (!skill) {
        throw new HTTPException(404, { message: `Stored skill with id ${storedSkillId} not found` });
      }
      assertStoredResourceScope(skill, await getStoredResourceScope(mastra, requestContext));

      assertReadAccess({ requestContext, resource: 'stored-skills', resourceId: storedSkillId, record: skill });

      return enrichOrStripFavorites(mastra, requestContext, 'skill', skill);
    } catch (error) {
      return handleError(error, 'Error getting stored skill');
    }
  },
});

/**
 * POST /stored/skills - Create a new stored skill
 */
export const CREATE_STORED_SKILL_ROUTE = createRoute({
  method: 'POST',
  path: '/stored/skills',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the skill ID exists by listing stored skills (GET /api/stored-skills) and using an ID from that list
2. Check that the Mastra instance is configured with the same storage backend where the skill was created
3. Re-create the skill if it was deleted (POST /api/stored-skills) and use the returned ID
4. Handle the 404 in the client instead of retrying — it is a definitive miss

Example fix

// before
const skill = await fetch(`/api/stored-skills/${id}`).then(r => r.json());
// after
const res = await fetch(`/api/stored-skills/${id}`);
if (res.status === 404) {
  console.warn(`Skill ${id} not found; listing available skills`);
} else {
  const skill = await res.json();
}

const exists = async (id: string) =>
  (await fetch(`/api/stored-skills/${id}`)).status !== 404;
if (!(await exists(id))) throw new Error(`Skip: skill ${id} missing`);

function isHttp404(e: unknown): e is { status: 404 } {
  return typeof e === 'object' && e !== null && (e as any).status === 404;
}

try {
  const skill = await getStoredSkill(id);
} catch (e) {
  if (isHttp404(e)) {
    console.warn(`Skill ${id} not found; refresh ID list`);
    return null; // treat as recoverable miss
  }
  throw e;
}

When it happens

Trigger: GET /api/stored-skills/:id where the id does not exist in the skills store; the skill was deleted by another user/process; the caller targets the wrong Mastra instance or storage backend; a typo'd or stale ID from a previous create call.

Common situations: Client cached an ID from a skill that was later deleted; environment points at an empty/different database (e.g. dev vs prod storage); ID was slugified differently than expected; testing against a fresh LibSQL/Postgres instance with no seeded 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

• Stored scorer definition with id ${storedScorerId} 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/a34387629373d7b7. Report an issue: GitHub.