shadcn-ui/ui · error · RegistryItemNotFoundError

NOT_FOUND

NOT_FOUND

Error message

Registry item "${itemName}" was not found.

What it means

Thrown by loadRegistryItem when the registry was loaded and its includes resolved, but no item in result.registry.items has a name equal to the requested itemName. RegistryItemNotFoundError is a clean 404-class error distinct from the file/parse errors that can occur earlier in loadRegistryItem.

Source

Thrown at packages/shadcn/src/registry/loader.ts:57

export async function loadRegistry(options?: LoadRegistryOptions) {
  const { cwd, registryFile } = resolveLoadRegistryOptions(options)
  const result = await readRegistryWithIncludes(registryFile, { cwd })
  const rootDir = getRegistryRootDir(result, cwd, registryFile)

  return createRegistryCatalog(result, rootDir, cwd)
}

export async function loadRegistryItem(
  itemName: string,
  options?: LoadRegistryOptions
) {
  const { cwd, registryFile } = resolveLoadRegistryOptions(options)
  const result = await readRegistryWithIncludes(registryFile, { cwd })
  const item = result.registry.items.find((item) => item.name === itemName)

  if (!item) {
    throw new RegistryItemNotFoundError(itemName)
  }

  const rootDir = getRegistryRootDir(result, cwd, registryFile)

  return createRegistryItem(item, result, rootDir, cwd)
}

export async function readRegistryWithIncludes(
  registryFile: string,
  options: {
    cwd: string
  }
) {
  const rootFile = path.resolve(options.cwd, registryFile)
  const content = await readRegistryJson(rootFile)
  const rootRegistry = parseRegistry(content, rootFile)
  validateRootRegistry(rootRegistry, rootFile)
  const context = {

View on GitHub (pinned to efac598707)

Solutions

1. Print the loaded catalog's item names to confirm what is actually available.
2. Fix the item name to match an existing 'name' in items[].
3. If the item is in a separate registry.json, ensure that file is listed under 'include' in the root.
4. Re-run loadRegistry (full catalog) and inspect the resolved items list.

Example fix

// before
loadRegistryItem("buton", { cwd: projectRoot })

// after (name matches items[].name)
loadRegistryItem("button", { cwd: projectRoot })

import { loadRegistry } from "@/src/registry/loader";

async function assertItemInRegistry(itemName: string, options?: LoadRegistryOptions) {
  const catalog = await loadRegistry(options);
  if (!catalog.items.some(i => i.name === itemName)) {
    throw new Error(`Item "${itemName}" not in registry. Available: ${catalog.items.map(i => i.name).join(", ")}`);
  }
}

function itemInCatalog(catalog: { items: { name: string }[] }, name: string): boolean {
  return catalog.items.some(i => i.name === name);
}

try {
  await loadRegistryItem(itemName, options);
} catch (err) {
  if (err instanceof RegistryItemNotFoundError) {
    // load the full catalog and suggest the closest matching item name
  }
  throw err;
}

When it happens

Trigger: Calling loadRegistryItem("button", ...) against a registry.json whose items[] has no item named "button", or where the item lives in an include that was not wired into the root registry.

Common situations: Typo in the item name, item renamed, item declared in a separate registry file never added to 'include', or calling loadRegistryItem on a catalog whose items are gated behind includes that failed silently upstream.

Related errors

• NOT_FOUND
• NOT_FOUND
• VALIDATION_ERROR
• PARSE_ERROR
• NOT_CONFIGURED

AI-assisted analysis of shadcn-ui/ui@efac598707 (2026-08-12). Data as JSON: /api/errors/7540e560de6aa751. Report an issue: GitHub.