shadcn-ui/ui · error · RegistrySourceFileError

refError.message

Error message

refError.message

What it means

This error is thrown when GitHub ref resolution fails because the `gh` CLI binary is not installed (ENOENT when spawning `gh`) or the available auth mode has no valid GitHub credentials. The library deliberately preserves the original ref-resolution message (e.g. 'Failed to resolve GitHub ref ...') and re-wraps it in a RegistrySourceFileError with reason 'github-ref-resolution', attaching setup guidance (install gh / gh auth login / set GH_TOKEN). It indicates an environment/credentials problem rather than a missing branch or tag.

Source

Thrown at packages/shadcn/src/registry/github-ref.ts:183

  try {
    return await resolveGitHubRefViaAuth(address, ref, mode)
  } catch (error) {
    if (!(error instanceof GitHubTransportError)) {
      throw refError
    }

    // An authenticated 404 preserves the original error so private and
    // missing repositories stay ambiguous.
    if (error.kind === "http" && error.statusCode === 404) {
      throw refError
    }

    const guidance = getGitHubTransportFailureGuidance(error, mode)

    // A missing gh binary or missing credentials keeps the original message
    // and adds setup guidance.
    if (error.kind === "enoent" || error.kind === "unauthenticated") {
      throw new RegistrySourceFileError("registry.json", undefined, {
        message: refError.message,
        context: {
          reason: "github-ref-resolution",
          source: formatGitHubSource(address),
          ref,
        },
        suggestion: guidance.suggestion,
      })
    }
    throw new RegistrySourceFileError("registry.json", undefined, {
      message: `Failed to resolve GitHub ref "${ref}" for ${address.owner}/${address.repo}. ${guidance.detail}`,
      context: {
        reason: "github-ref-resolution",
        source: formatGitHubSource(address),
        ref,
      },
      suggestion: guidance.suggestion,
    })

View on GitHub (pinned to 683a5a9b37)

Solutions

1. Install the GitHub CLI (https://cli.github.com) and confirm `gh --version` works in the same shell/PATH used by your tool
2. Authenticate with `gh auth login` or export a valid GH_TOKEN / GITHUB_TOKEN with repo read access
3. Verify credentials with `gh auth status` and re-run the registry command
4. If in CI or Docker, add the gh binary or a token secret to the image/environment
5. If you cannot use gh, ensure `git` is installed so ref resolution succeeds via `git ls-remote` without needing the gh fallback

Example fix

# before
gh: not found / no valid GitHub credentials -> Failed to resolve GitHub ref "main"

# after
brew install gh  # or apt install gh
gh auth login
# or: export GH_TOKEN=$(gh auth token)
npx shadcn add owner/repo

import { execSync } from "node:child_process"

function ghAvailable(): boolean {
  try { execSync("gh --version", { stdio: "ignore" }); return true } catch { return false }
}
function gitAvailable(): boolean {
  try { execSync("git --version", { stdio: "ignore" }); return true } catch { return false }
}
// before resolving refs from a GitHub registry:
if (!ghAvailable() && !gitAvailable()) {
  throw new Error("Install git or the GitHub CLI before fetching GitHub registries")
}
if (ghAvailable() && !process.env.GH_TOKEN && !process.env.GITHUB_TOKEN) {
  // private repos will fail without credentials; warn or run `gh auth status`
}

function isRegistrySourceFileError(e: unknown): e is RegistrySourceFileError {
  return e instanceof RegistrySourceFileError
}
function isGitHubRefResolutionFailure(e: unknown): boolean {
  return isRegistrySourceFileError(e) && e.context?.reason === "github-ref-resolution"
}

try {
  await addFromGitHubRegistry(address, ref)
} catch (error) {
  if (isRegistrySourceFileError(error) && error.context?.reason === "github-ref-resolution") {
    // check error.suggestion for setup guidance (install gh / gh auth login / GH_TOKEN)
    console.error(error.message, error.suggestion)
    return
  }
  throw error
}

When it happens

Trigger: Calling a registry API that resolves a GitHub ref (e.g. adding from a GitHub-hosted shadcn registry) when: (1) `git ls-remote` already failed and the fallback to `gh` CLI runs but the `gh` binary is missing (error.kind === 'enoent' from spawning gh), or (2) the selected auth mode is 'token'/'gh' but GitHub reports no valid credentials (error.kind === 'unauthenticated'). The original refError.message is kept and a suggestion with setup steps is added.

Common situations: CI runners or Docker images without the GitHub CLI installed; tokens expired or revoked (GH_TOKEN/GITHUB_TOKEN env vars set to stale values); corporate machines where `gh auth login` was never run; sandboxed environments where the `gh` binary is not on PATH; fresh clones on new developer machines.

Related errors

• Failed to resolve GitHub ref "${ref}" for ${address.owner}/$
• VALIDATION_ERROR
• Unknown ${flag} target "${target}". Valid targets: ${valid}.
• --style ${target} is not supported because it is a legacy so
• Invalid registry namespace: ${namespace}. Registry names mus

AI-assisted analysis of shadcn-ui/ui@683a5a9b37 (2026-08-27). Data as JSON: /api/errors/ec08da2652fd6f3c. Report an issue: GitHub.