{"record":{"id":"ec08da2652fd6f3c","repo":"shadcn-ui/ui","slug":"referror-message","errorCode":null,"errorMessage":"refError.message","messagePattern":"refError\\.message","errorType":"exception","errorClass":"RegistrySourceFileError","httpStatus":null,"severity":"error","filePath":"packages/shadcn/src/registry/github-ref.ts","lineNumber":183,"sourceCode":"  try {\n    return await resolveGitHubRefViaAuth(address, ref, mode)\n  } catch (error) {\n    if (!(error instanceof GitHubTransportError)) {\n      throw refError\n    }\n\n    // An authenticated 404 preserves the original error so private and\n    // missing repositories stay ambiguous.\n    if (error.kind === \"http\" && error.statusCode === 404) {\n      throw refError\n    }\n\n    const guidance = getGitHubTransportFailureGuidance(error, mode)\n\n    // A missing gh binary or missing credentials keeps the original message\n    // and adds setup guidance.\n    if (error.kind === \"enoent\" || error.kind === \"unauthenticated\") {\n      throw new RegistrySourceFileError(\"registry.json\", undefined, {\n        message: refError.message,\n        context: {\n          reason: \"github-ref-resolution\",\n          source: formatGitHubSource(address),\n          ref,\n        },\n        suggestion: guidance.suggestion,\n      })\n    }\n    throw new RegistrySourceFileError(\"registry.json\", undefined, {\n      message: `Failed to resolve GitHub ref \"${ref}\" for ${address.owner}/${address.repo}. ${guidance.detail}`,\n      context: {\n        reason: \"github-ref-resolution\",\n        source: formatGitHubSource(address),\n        ref,\n      },\n      suggestion: guidance.suggestion,\n    })","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/shadcn-ui/ui/blob/683a5a9b370acdb7785a0529434e6a3b8c7e0441/packages/shadcn/src/registry/github-ref.ts#L165-L201","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the GitHub CLI (https://cli.github.com) and confirm `gh --version` works in the same shell/PATH used by your tool","Authenticate with `gh auth login` or export a valid GH_TOKEN / GITHUB_TOKEN with repo read access","Verify credentials with `gh auth status` and re-run the registry command","If in CI or Docker, add the gh binary or a token secret to the image/environment","If you cannot use gh, ensure `git` is installed so ref resolution succeeds via `git ls-remote` without needing the gh fallback"],"exampleFix":"# before\ngh: not found / no valid GitHub credentials -> Failed to resolve GitHub ref \"main\"\n\n# after\nbrew install gh  # or apt install gh\ngh auth login\n# or: export GH_TOKEN=$(gh auth token)\nnpx shadcn add owner/repo","handlingStrategy":"fallback","validationCode":"import { execSync } from \"node:child_process\"\n\nfunction ghAvailable(): boolean {\n  try { execSync(\"gh --version\", { stdio: \"ignore\" }); return true } catch { return false }\n}\nfunction gitAvailable(): boolean {\n  try { execSync(\"git --version\", { stdio: \"ignore\" }); return true } catch { return false }\n}\n// before resolving refs from a GitHub registry:\nif (!ghAvailable() && !gitAvailable()) {\n  throw new Error(\"Install git or the GitHub CLI before fetching GitHub registries\")\n}\nif (ghAvailable() && !process.env.GH_TOKEN && !process.env.GITHUB_TOKEN) {\n  // private repos will fail without credentials; warn or run `gh auth status`\n}","typeGuard":"function isRegistrySourceFileError(e: unknown): e is RegistrySourceFileError {\n  return e instanceof RegistrySourceFileError\n}\nfunction isGitHubRefResolutionFailure(e: unknown): boolean {\n  return isRegistrySourceFileError(e) && e.context?.reason === \"github-ref-resolution\"\n}","tryCatchPattern":"try {\n  await addFromGitHubRegistry(address, ref)\n} catch (error) {\n  if (isRegistrySourceFileError(error) && error.context?.reason === \"github-ref-resolution\") {\n    // check error.suggestion for setup guidance (install gh / gh auth login / GH_TOKEN)\n    console.error(error.message, error.suggestion)\n    return\n  }\n  throw error\n}","preventionTips":["Install the GitHub CLI and run `gh auth login` in CI and dev environments","Set GH_TOKEN/GITHUB_TOKEN as a CI secret with repo read scope","Ensure `git` is installed so the ls-remote path works without gh","Verify `gh auth status` passes before running registry commands in pipelines"],"tags":["github","authentication","cli","credentials","registry"],"backgroundTag":"github-auth-missing","analyzedSha":"683a5a9b370acdb7785a0529434e6a3b8c7e0441","analyzedAt":"2026-08-27T14:12:43.753Z","contentChangedAt":"2026-08-27T14:12:43.753Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}