{"record":{"id":"13ed1407b6f5822e","repo":"mastra-ai/mastra","slug":"skills-storage-domain-is-not-available","errorCode":null,"errorMessage":"Skills storage domain is not available","messagePattern":"Skills storage domain is not available","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"packages/server/src/server/handlers/builder-registry.ts","lineNumber":340,"sourceCode":"  pathParamSchema: builderRegistryPathParams,\n  bodySchema: builderRegistryInstallBodySchema,\n  responseSchema: builderRegistryInstallResponseSchema,\n  summary: 'Install a registry skill into stored skills',\n  description: 'Fetches a skill from the configured registry and persists it as a new stored skill.',\n  tags: ['Editor', 'Skills'],\n  requiresAuth: true,\n  requiresPermission: 'stored-skills:write',\n  handler: async ({ mastra, requestContext, registryId, owner, repo, skillName, visibility: bodyVisibility }) => {\n    try {\n      await requireEnabledRegistry(mastra, registryId);\n\n      const storage = mastra.getStorage();\n      if (!storage) {\n        throw new HTTPException(500, { message: 'Storage is not configured' });\n      }\n      const skillStore = await storage.getStore('skills');\n      if (!skillStore) {\n        throw new HTTPException(500, { message: 'Skills storage domain is not available' });\n      }\n\n      // Pull files from the registry\n      const result = await fetchSkillFiles(owner, repo, skillName);\n      if (!result || result.files.length === 0) {\n        throw new HTTPException(404, {\n          message: `Could not find skill \"${skillName}\" in ${owner}/${repo}.`,\n        });\n      }\n\n      const safeSkillId = assertSafeSkillName(result.skillId);\n      const files = buildFileTree(result.files);\n\n      // Parse SKILL.md frontmatter into structured fields. Splitting\n      // frontmatter (name/description) from the markdown body keeps the\n      // body as the agent-facing `instructions` instead of polluting it\n      // with raw YAML metadata. SKILL.md missing or unparseable simply\n      // yields a null snapshot — registry-provided values then fill in.","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/builder-registry.ts#L322-L358","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Upgrade the storage adapter package to a version that implements the skills store domain.","Check the adapter's supported store domains and confirm 'skills' is listed.","If using a custom storage implementation, add the skills domain store.","Align @mastra/core and the storage package versions so expected and provided domains match."],"exampleFix":"// before\n\"@mastra/storage-libsql\": \"^0.1.0\" // predates skills domain\n\n// after\n\"@mastra/storage-libsql\": \"latest\" // includes getStore('skills') support","handlingStrategy":"validation","validationCode":"const storage = mastra.getStorage();\nif (!storage) throw new Error('no storage');\nconst skillsStore = await storage.getStore('skills');\nif (!skillsStore) throw new Error('storage adapter lacks skills domain — upgrade adapter');","typeGuard":"function supportsSkillsDomain(s: { getStore(name: string): Promise<unknown> }): Promise<boolean> {\n  return s.getStore('skills').then(v => v != null);\n}","tryCatchPattern":"try {\n  await installSkill(payload);\n} catch (e) {\n  if (e.status === 500 && e.message.includes('Skills storage domain')) {\n    // flag adapter version incompatibility; prompt upgrade\n  } else throw e;\n}","preventionTips":["Keep the storage adapter package version aligned with @mastra/core and @mastra/server.","Check the adapter's supported store domains in its docs before enabling skills features.","Pin compatible versions in the lockfile; watch for partial upgrades in monorepos.","Smoke-test getStore('skills') in a startup health check."],"tags":["http-500","storage","skills","version-mismatch"],"backgroundTag":"storage-domain-unsupported","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}