mastra-ai/mastra · error · HTTPException

Skills storage domain is not available

Error message

Skills storage domain is not available

What it means

After storage is present, the install-skill handler requests the 'skills' store domain via storage.getStore('skills') and throws a 500 HTTPException when the store is unavailable. This means the configured storage backend does not implement or expose the skills domain, so imported registry skills cannot be saved even though storage itself exists.

Source

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

  pathParamSchema: builderRegistryPathParams,
  bodySchema: builderRegistryInstallBodySchema,
  responseSchema: builderRegistryInstallResponseSchema,
  summary: 'Install a registry skill into stored skills',
  description: 'Fetches a skill from the configured registry and persists it as a new stored skill.',
  tags: ['Editor', 'Skills'],
  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.

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade the storage adapter package to a version that implements the skills store domain.
2. Check the adapter's supported store domains and confirm 'skills' is listed.
3. If using a custom storage implementation, add the skills domain store.
4. Align @mastra/core and the storage package versions so expected and provided domains match.

Example fix

// before
"@mastra/storage-libsql": "^0.1.0" // predates skills domain

// after
"@mastra/storage-libsql": "latest" // includes getStore('skills') support

const storage = mastra.getStorage();
if (!storage) throw new Error('no storage');
const skillsStore = await storage.getStore('skills');
if (!skillsStore) throw new Error('storage adapter lacks skills domain — upgrade adapter');

function supportsSkillsDomain(s: { getStore(name: string): Promise<unknown> }): Promise<boolean> {
  return s.getStore('skills').then(v => v != null);
}

try {
  await installSkill(payload);
} catch (e) {
  if (e.status === 500 && e.message.includes('Skills storage domain')) {
    // flag adapter version incompatibility; prompt upgrade
  } else throw e;
}

When it happens

Trigger: Calling the builder-registry install route against a Mastra instance whose storage adapter lacks the 'skills' store (older storage adapter, a storage backend without skills-domain support, or an adapter version predating the skills store).

Common situations: Upgraded @mastra/server but still on an older storage package that predates the skills domain; using a minimal/custom storage implementation that only implements some domains; dependency drift where core expects a newer storage adapter than installed.

Related errors

• Scorer definitions storage domain is not available
• Skills storage domain is not available
• Failed to resolve skill after publish
• AcpAgent does not support resuming suspended generate calls
• AcpAgent does not support resuming suspended stream calls

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