{"record":{"id":"96377209b5dc9778","repo":"shadcn-ui/ui","slug":"fetch-error-963772","errorCode":"FETCH_ERROR","errorMessage":"Could not resolve GitHub ref \"${ref}\" for ${address.owner}/${address.repo}.","messagePattern":"Could not resolve GitHub ref \"(.+?)\" for (.+?)/(.+?)\\.","errorType":"error_code","errorClass":"RegistrySourceFileError","httpStatus":null,"severity":"error","filePath":"packages/shadcn/src/registry/github-ref.ts","lineNumber":72,"sourceCode":"          GIT_TERMINAL_PROMPT: \"0\",\n        },\n        timeout: GITHUB_REF_RESOLUTION_TIMEOUT,\n      }\n    )\n    stdout = result.stdout\n  } catch (error) {\n    throw createGitHubRefResolutionError(address, ref, repoUrl, error)\n  }\n\n  const refs = parseGitLsRemote(stdout)\n  for (const candidate of getPreferredGitHubRefNames(ref)) {\n    const sha = refs.get(candidate)\n    if (sha) {\n      return sha\n    }\n  }\n\n  throw new RegistrySourceFileError(\"registry.json\", undefined, {\n    message: `Could not resolve GitHub ref \"${ref}\" for ${address.owner}/${address.repo}.`,\n    context: {\n      reason: \"github-ref-resolution\",\n      source: formatGitHubSource(address),\n      ref,\n      repoUrl,\n    },\n    suggestion:\n      'Use an existing branch, tag, or full commit SHA. For example: \"owner/repo/item#main\" or \"owner/repo/item#v1.0.0\".',\n  })\n}\n\nexport function getGitHubRefCandidates(ref: string) {\n  return Array.from(new Set(getPreferredGitHubRefNames(ref)))\n}\n\nexport function getPreferredGitHubRefNames(ref: string) {\n  if (ref === \"HEAD\") {","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/shadcn-ui/ui/blob/efac5987074af84ece57c367c6dd83387b967022/packages/shadcn/src/registry/github-ref.ts#L54-L90","documentation":"Thrown by resolveGitHubRefUncached after 'git ls-remote' succeeded but none of the preferred ref names (refs/heads/<ref>, refs/tags/<ref>, etc.) matched any advertised ref. RegistrySourceFileError signals that the ref string itself is syntactically fine but does not exist in the repository at the resolved default or specified ref.","triggerScenarios":"Pinning to a branch or tag that was deleted/renamed, a typo in the ref, or asking for a tag like 'v1.0.0' that does not exist. The 40-char SHA fast-path and the ls-remote call both ran without error; only the lookup failed.","commonSituations":"Branch renamed or deleted after an address was pinned, semantic confusion between branch and tag names, or referencing a ref from a fork that does not exist in the resolved repo.","solutions":["Use the exact 'git ls-remote https://github.com/owner/repo.git' output to find a real ref name.","Pin to a full 40-character commit SHA to bypass ref resolution entirely.","Use 'main'/'master' or the repo's current default branch if you do not need a specific ref.","Check whether the ref lives under refs/heads vs refs/tags and qualify it ('refs/tags/v1.0.0')."],"exampleFix":"// before\nadd(\"owner/repo/button#v0.9\")\n\n// after (verify with git ls-remote)\nadd(\"owner/repo/button#v1.0.0\")\n// or a commit SHA\nadd(\"owner/repo/button#a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2\")","handlingStrategy":"validation","validationCode":"import { execa } from \"execa\";\n\nasync function refExists(owner: string, repo: string, ref: string) {\n  const candidates = [\n    ref === \"HEAD\" ? \"HEAD\" : null,\n    ref.startsWith(\"refs/tags/\") ? `${ref}^{}` : null,\n    ref.startsWith(\"refs/\") ? ref : null,\n    `refs/heads/${ref}`, `refs/tags/${ref}^{}`, `refs/tags/${ref}`, ref,\n  ].filter(Boolean) as string[];\n  const { stdout } = await execa(\"git\", [\"ls-remote\", \"--symref\", \"--\", `https://github.com/${owner}/${repo}.git`, ...candidates]);\n  return /\\b[0-9a-f]{40}\\b/.test(stdout);\n}\n// call before resolveGitHubRef to fail with a clear, local error","typeGuard":"const SHA_40 = /^[a-fA-F0-9]{40}$/;\nfunction isFullCommitSha(ref: string): boolean {\n  return SHA_40.test(ref); // SHAs short-circuit ref resolution and never hit this error\n}","tryCatchPattern":"try {\n  await resolveGitHubRef(address);\n} catch (err) {\n  if (err instanceof RegistrySourceFileError && /Could not resolve GitHub ref/.test(err.message)) {\n    // fall back to the default branch or a known-good SHA\n  }\n  throw err;\n}","preventionTips":["Pin GitHub registry sources to a full 40-char SHA in production configs.","Verify branch/tag names with 'git ls-remote' before pinning.","Prefer refs/heads/<name> or refs/tags/<name> over bare names when ambiguous."],"tags":["github","git-ref","fetch-error","typescript"],"backgroundTag":null,"analyzedSha":"efac5987074af84ece57c367c6dd83387b967022","analyzedAt":"2026-08-12T05:00:50.218Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}