mastra-ai/mastra · error · HTTPException

Registry not found

Error message

Registry not found

What it means

requireEnabledRegistry resolves the configured builder registries on the Mastra instance and throws a 404 HTTPException when the requested registryId is absent from the list or present but disabled. It deliberately returns 404 (not 403) so that OFF registries are indistinguishable from nonexistent ones — no configuration surface leaks. It guards the search, popular, preview, and install builder-registry routes.

Source

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

  const registries = builder?.getRegistries?.();
  return [
    {
      id: 'skills-sh',
      enabled: registries?.skillsSh?.enabled === true,
      label: REGISTRY_LABELS['skills-sh']!,
    },
  ];
}

/**
 * Hard-gate: throws 404 when the requested registry is unknown or disabled.
 * Mirrors `requireBuilderFeature` semantics — no surface leak for OFF registries.
 */
async function requireEnabledRegistry(mastra: Mastra, registryId: string): Promise<void> {
  const list = await resolveRegistries(mastra);
  const match = list.find(r => r.id === registryId);
  if (!match || !match.enabled) {
    throw new HTTPException(404, { message: 'Registry not found' });
  }
}

// =============================================================================
// File-tree helpers
// =============================================================================

/**
 * Convert a flat list of `{ path, content, encoding }` entries into the
 * `StorageSkillFileNode` tree shape expected by the stored-skills create path.
 *
 * Each path is validated via `assertSafeFilePath` to prevent traversal from
 * upstream-controlled responses. Folder nodes are created on demand.
 */
function buildFileTree(
  files: Array<{ path: string; content: string; encoding: 'utf-8' | 'base64' }>,
): StorageSkillFileNode[] {
  const root: StorageSkillFileNode[] = [];

View on GitHub (pinned to 75dd419e61)

Solutions

1. Confirm the registryId matches an ID in the server's configured registry list (resolveRegistries output).
2. Enable the registry in the server configuration if it exists but is disabled.
3. Call the registry-list endpoint (or inspect server config) to discover valid registry IDs before calling search/preview/install.
4. If the registry should exist, verify you are hitting the correct Mastra server/deployment where it is configured.

Example fix

// before
await fetch('/api/builder/registry/my-registry/search?q=skills');

// after
const registries = await fetch('/api/builder/registries').then(r => r.json());
const reg = registries.find(r => r.id === 'my-registry' && r.enabled);
if (!reg) throw new Error('Registry not configured or disabled on this server');

const registries = await listRegistries();
const reg = registries.find(r => r.id === registryId);
if (!reg || !reg.enabled) throw new Error(`Registry "${registryId}" is not available on this server`);

function isRegistryAvailable(r: { id: string; enabled: boolean } | undefined): r is { id: string; enabled: true } {
  return !!r && r.enabled === true;
}

When it happens

Trigger: Any BUILDER_REGISTRY route (search, popular, preview, install) called with a registryId that is not in the resolved registry list, or whose entry has enabled=false.

Common situations: Typo or stale registry ID in client code; registry was disabled via configuration/environment after a client cached its ID; multi-tenant setup where the registry exists on another instance; registries not configured at all on this server.

Related errors

• Could not find skill "${skillName}" in ${owner}/${repo}.
• 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/2bbc8e226123eb52. Report an issue: GitHub.