Invalid registry URL for ${namespace}. URL must include {nam

Error message

Invalid registry URL for ${namespace}. URL must include {name} placeholder. Example: ${namespace}=https://example.com/r/{name}.json

What it means

When a registry URL is supplied inline, it MUST contain the literal {name} placeholder so the resolver can substitute each component name at fetch time. Without it, the CLI cannot build per-item URLs and rejects the template.

Source

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

    }
    fetchSpinner.succeed()
    registriesIndex = registries
  }

  const registriesToAdd: Record<string, string> = {}
  for (const { namespace, url } of parsed) {
    if (namespace in BUILTIN_REGISTRIES) {
      logger.warn(
        `${highlighter.info(
          namespace
        )} is a built-in registry and cannot be added.`
      )
      continue
    }

    if (url) {
      if (!url.includes("{name}")) {
        throw new Error(
          `Invalid registry URL for ${highlighter.info(
            namespace
          )}. URL must include {name} placeholder. Example: ${highlighter.info(
            `${namespace}=https://example.com/r/{name}.json`
          )}`
        )
      }
      registriesToAdd[namespace] = url
    } else {
      const registry = registriesIndex.find((r) => r.name === namespace)
      if (!registry) {
        throw new Error(
          `Registry ${highlighter.info(namespace)} not found. ` +
            `Provide a URL: ${highlighter.info(
              `${namespace}=https://.../{name}.json`
            )}`
        )
      }

View on GitHub (pinned to efac598707)

Solutions

Include {name} in the URL: `shadcn registry add @acme=https://example.com/r/{name}.json`.
Confirm the registry's documented template path before adding.

Example fix

// before
shadcn registry add @acme=https://example.com/r/button.json
// after
shadcn registry add @acme=https://example.com/r/{name}.json

Defensive patterns

Strategy: validation

Validate before calling

function assertRegistryUrlTemplate(namespace: string, url: string) {
  if (!url.includes("{name}")) {
    throw new Error(`URL for ${namespace} must contain the {name} placeholder.`)
  }
}

Type guard

function isValidRegistryUrlTemplate(url: string): boolean {
  return url.includes("{name}")
}

Prevention

Always templatize registry URLs with {name}.
Document the placeholder convention for custom registries.

When it happens

Trigger: Running `shadcn registry add @acme=https://example.com/r/button.json` (hardcoded component) instead of a templated URL containing {name}.

Common situations: Misunderstanding the URL-template contract, pasting a concrete item URL instead of the pattern, URL-encoding that strips the braces, registry docs that show a final URL rather than the template.

Related errors

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