shadcn-ui/ui · error · RegistryValidationError

VALIDATION_ERROR

VALIDATION_ERROR

Error message

Invalid GitHub ref in registry source "${source}".

What it means

RegistryValidationError (code VALIDATION_ERROR) thrown by resolveGitHubRegistrySource when the source string has a valid `owner/repo` shape but the optional `#ref` portion fails isValidGitHubRef. A valid ref must be non-empty, contain no control characters, no whitespace, and not start with a dash. The error includes a suggestion describing the rules and context with the offending source and ref.

Source

Thrown at packages/shadcn/src/registry/address.ts:100

}

export function resolveGitHubRegistrySource(source: string) {
  const hashIndex = source.indexOf("#")
  const path = hashIndex === -1 ? source : source.slice(0, hashIndex)
  const ref = hashIndex === -1 ? undefined : source.slice(hashIndex + 1)
  const parts = path.split("/")

  if (parts.length !== 2) {
    return null
  }

  const [owner, repo] = parts
  if (!isGitHubOwner(owner) || !isGitHubRepo(repo)) {
    return null
  }

  if (ref !== undefined && !isValidGitHubRef(ref)) {
    throw new RegistryValidationError(
      `Invalid GitHub ref in registry source "${source}".`,
      {
        context: {
          source,
          ref,
        },
        suggestion:
          "Use a non-empty branch, tag, or commit SHA without whitespace, control characters or leading dashes.",
      }
    )
  }

  return {
    owner,
    repo,
    ref,
  } satisfies ResolvedGitHubRegistrySource
}

View on GitHub (pinned to efac598707)

Solutions

1. Use a plain branch, tag, or 40-char commit SHA with no whitespace or leading dash.
2. Quote the source string in components.json to preserve exact characters.
3. If you intended `#-branch`, rename the branch (Git disallows leading-dash refs anyway).
4. Validate before configuring: `git ls-remote https://github.com/owner/repo <ref>`.

Example fix

// before — ref with leading dash / whitespace
"registries": { "@gh": "owner/repo#-main" }
"registries": { "@gh": "owner/repo#feat work" }

// after — clean ref
"registries": { "@gh": "owner/repo#main" }
"registries": { "@gh": "owner/repo#feat-work" }
// or a commit SHA
"registries": { "@gh": "owner/repo#abcdef0123456789abcdef0123456789abcdef01" }

import { resolveGitHubRegistrySource } from '@/src/registry/address'

function assertValidGitHubSource(source: string) {
  // Returns null for non-github shapes (no throw); throws RegistryValidationError for bad refs.
  resolveGitHubRegistrySource(source)
}

// wrap in try/catch to surface the suggestion cleanly:
try { assertValidGitHubSource(source) } catch (e) { /* e.suggestion, e.context.ref */ }

const CONTROL = /[\x00-\x1F\x7F]/
const SPACE = /\s/
const LEADING_DASH = /^-/

function isValidGitHubRef(ref: string): boolean {
  return !!ref && !CONTROL.test(ref) && !SPACE.test(ref) && !LEADING_DASH.test(ref)
}

function isValidGitHubSource(source: string): boolean {
  const hash = source.indexOf('#')
  if (hash === -1) return true
  const ref = source.slice(hash + 1)
  return ref === '' ? false : isValidGitHubRef(ref)
}

import { RegistryValidationError } from '@/src/registry/errors'

try {
  resolveGitHubRegistrySource(source)
} catch (e) {
  if (e instanceof RegistryValidationError && e.code === 'VALIDATION_ERROR') {
    logger.error(`Bad GitHub ref in '${source}': ${e.suggestion}`)
    // prompt the user for a corrected ref
  } else throw e
}

When it happens

Trigger: Configuring a registry source like `owner/repo# my-branch` (leading space), `owner/repo#-branch` (leading dash, mistaken CLI flag), `owner/repo#feat branch` (internal space), or `owner/repo#<tab>` (control char). Also an empty ref after `#` like `owner/repo#`.

Common situations: User typed a branch name with a space; copy-pasted a ref that included a leading `-` from a command-line-style note; ref contains a newline/tab from a misformatted config file; shell quoting stripped part of the ref.

Related errors

• INVALID_CONFIG
• The provided cwd must match config.resolvedPaths.cwd.
• A full project config is required to resolve target aliases.
• MISSING_ENV_VARS
• "${registryName}" is a built-in registry and cannot be overr

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