Invalid registry namespace

Error message

Invalid registry namespace: ${namespace}. Registry names must start with @ (e.g., @acme).

What it means

parseRegistryArg splits the CLI arg on '=' and requires the namespace portion to start with '@' (e.g., @acme). This matches npm-style scoped names and lets the resolver distinguish a namespace from a URL.

Solutions

Prefix the namespace with '@': `shadcn registry add @acme`.
For a URL-backed registry: `shadcn registry add @acme=https://example.com/r/{name}.json`.

Example fix

// before
shadcn registry add acme
// after
shadcn registry add @acme

Defensive patterns

Strategy: validation

Validate before calling

function assertRegistryArg(arg: string) {
  const ns = arg.split("=")[0]
  if (!ns.startsWith("@")) {
    throw new Error(`Registry namespace must start with '@': got ${ns}`)
  }
}

Type guard

function isValidRegistryArg(arg: string): boolean {
  return arg.split("=")[0].startsWith("@")
}

Prevention

Always namespace registry args with '@'.
Document the '@acme' convention in team READMEs.

When it happens

Trigger: Running `shadcn registry add <name>[=url]` where the first '='-separated segment doesn't begin with '@'.

Common situations: Forgetting the '@' prefix, typing a bare vendor name (acme instead of @acme), accidentally pasting a URL as the first segment.

Related errors

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

Appendix: source

Thrown at packages/shadcn/src/commands/registry/add.ts:60

      await addRegistriesToConfig(registryArgs, options.cwd, {
        silent: options.silent,
      })
    } catch (error) {
      logger.break()
      handleError(error)
    }
  })

export function parseRegistryArg(arg: string): {
  namespace: string
  url?: string
} {
  const [namespace, ...rest] = arg.split("=")
  const url = rest.length > 0 ? rest.join("=") : undefined

  if (!namespace.startsWith("@")) {
    throw new Error(
      `Invalid registry namespace: ${highlighter.info(namespace)}. ` +
        `Registry names must start with @ (e.g., @acme).`
    )
  }

  return { namespace, url }
}

function pluralize(count: number, singular: string, plural: string) {
  return `${count} ${count === 1 ? singular : plural}`
}

export async function addRegistriesToConfig(
  registryArgs: string[],
  cwd: string,
  options: { silent?: boolean }
) {
  // Write to components.json when it exists, otherwise fall back to

View on GitHub (pinned to c06da1d0e9)