shadcn-ui/ui · error · RegistryInvalidNamespaceError

VALIDATION_ERROR

VALIDATION_ERROR

Error message

Invalid registry namespace: "${name}". Registry names must start with @ (e.g., @shadcn, @v0).

What it means

Thrown by getRegistryWithContext after the URL and GitHub-source branches are ruled out, when the supplied name does not begin with '@'. The CLI treats un-prefixed, non-URL, non-GitHub names as invalid for the registry catalog API because namespace-prefixed names (@shadcn, @v0, custom @yourorg) are the only way to resolve a configured registry endpoint.

Source

Thrown at packages/shadcn/src/registry/api.ts:126

  options?: GetRegistryOptions
) {
  const { config, useCache, searchParams } = options || {}

  if (isUrl(name)) {
    const url = appendSearchParamsToUrl(name, searchParams)
    const [result] = await fetchRegistry([url], { useCache })
    return parseRegistryCatalog(name, result)
  }

  // GitHub registries are raw files. There is no server to run a search, so
  // search params are not forwarded and filtering happens locally.
  const githubSource = resolveGitHubRegistrySource(name)
  if (githubSource) {
    return fetchGitHubRegistryCatalog(githubSource, { useCache })
  }

  if (!name.startsWith("@")) {
    throw new RegistryInvalidNamespaceError(name)
  }

  let registryName = name
  if (!registryName.endsWith("/registry")) {
    registryName = `${registryName}/registry`
  }

  const urlAndHeaders = buildUrlAndHeadersForRegistryItem(
    registryName as `@${string}`,
    configWithDefaults(config)
  )

  if (!urlAndHeaders?.url) {
    throw new RegistryNotFoundError(registryName)
  }

  // Append search params before registering headers so the header lookup key
  // matches the URL we actually fetch.

View on GitHub (pinned to efac598707)

Solutions

Prefix the name with '@', e.g. "@shadcn", "@yourorg", or "@yourorg/registry".
If you meant a direct endpoint, pass a full http(s) URL instead of a bare name.
If you meant a GitHub source, use the owner/repo form (with optional '#ref') which the GitHub branch handles.
Double-check you are calling the right function: getRegistry takes a registry name, not an item name.

Example fix

// before
getRegistry("myorg")

// after
getRegistry("@myorg")
// or a direct URL
getRegistry("https://example.com/registry.json")

Defensive patterns

Strategy: validation

Validate before calling

function assertRegistryNamespace(name: string) {
  if (!name.startsWith("@")) {
    throw new Error(`Registry name must start with '@': got ${JSON.stringify(name)}`);
  }
}
// call before getRegistry
assertRegistryNamespace(name);
await getRegistry(name);

Type guard

function isRegistryNamespace(name: string): name is `@${string}` {
  return name.startsWith("@");
}

Try / catch

try {
  await getRegistry(name);
} catch (err) {
  if (err instanceof RegistryInvalidNamespaceError) {
    // prompt user to prefix with '@' or treat as URL/GitHub source
  }
  throw err;
}

Prevention

Validate the '@' prefix at the UI/CLI boundary before calling getRegistry.
Keep a single helper that classifies input as URL | namespace | GitHub source | local file.
Document that getRegistry takes a registry name, not an item name.

When it happens

Trigger: Calling getRegistry("foo"), getRegistry("button"), or getRegistry("some-name") where the string is not a URL, does not match the owner/repo GitHub source shape, and lacks a leading '@'. Also triggered by typos like "shadcn" instead of "@shadcn".

Common situations: User forgets the '@' prefix when referencing a custom registry, or passes a bare component name where a registry name is expected. Confusing getRegistry (which wants a registry namespace) with getRegistryItems (which wants item names).

Related errors

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