{"record":{"id":"e695f7b05a95079f","repo":"shadcn-ui/ui","slug":"validation-error","errorCode":"VALIDATION_ERROR","errorMessage":"Invalid GitHub ref in registry source \"${source}\".","messagePattern":"Invalid GitHub ref in registry source \"(.+?)\"\\.","errorType":"validation","errorClass":"RegistryValidationError","httpStatus":null,"severity":"error","filePath":"packages/shadcn/src/registry/address.ts","lineNumber":100,"sourceCode":"}\n\nexport function resolveGitHubRegistrySource(source: string) {\n  const hashIndex = source.indexOf(\"#\")\n  const path = hashIndex === -1 ? source : source.slice(0, hashIndex)\n  const ref = hashIndex === -1 ? undefined : source.slice(hashIndex + 1)\n  const parts = path.split(\"/\")\n\n  if (parts.length !== 2) {\n    return null\n  }\n\n  const [owner, repo] = parts\n  if (!isGitHubOwner(owner) || !isGitHubRepo(repo)) {\n    return null\n  }\n\n  if (ref !== undefined && !isValidGitHubRef(ref)) {\n    throw new RegistryValidationError(\n      `Invalid GitHub ref in registry source \"${source}\".`,\n      {\n        context: {\n          source,\n          ref,\n        },\n        suggestion:\n          \"Use a non-empty branch, tag, or commit SHA without whitespace, control characters or leading dashes.\",\n      }\n    )\n  }\n\n  return {\n    owner,\n    repo,\n    ref,\n  } satisfies ResolvedGitHubRegistrySource\n}","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/shadcn-ui/ui/blob/efac5987074af84ece57c367c6dd83387b967022/packages/shadcn/src/registry/address.ts#L82-L118","documentation":"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.","triggerScenarios":"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#`.","commonSituations":"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.","solutions":["Use a plain branch, tag, or 40-char commit SHA with no whitespace or leading dash.","Quote the source string in components.json to preserve exact characters.","If you intended `#-branch`, rename the branch (Git disallows leading-dash refs anyway).","Validate before configuring: `git ls-remote https://github.com/owner/repo <ref>`."],"exampleFix":"// before — ref with leading dash / whitespace\n\"registries\": { \"@gh\": \"owner/repo#-main\" }\n\"registries\": { \"@gh\": \"owner/repo#feat work\" }\n\n// after — clean ref\n\"registries\": { \"@gh\": \"owner/repo#main\" }\n\"registries\": { \"@gh\": \"owner/repo#feat-work\" }\n// or a commit SHA\n\"registries\": { \"@gh\": \"owner/repo#abcdef0123456789abcdef0123456789abcdef01\" }","handlingStrategy":"type-guard","validationCode":"import { resolveGitHubRegistrySource } from '@/src/registry/address'\n\nfunction assertValidGitHubSource(source: string) {\n  // Returns null for non-github shapes (no throw); throws RegistryValidationError for bad refs.\n  resolveGitHubRegistrySource(source)\n}\n\n// wrap in try/catch to surface the suggestion cleanly:\ntry { assertValidGitHubSource(source) } catch (e) { /* e.suggestion, e.context.ref */ }","typeGuard":"const CONTROL = /[\\x00-\\x1F\\x7F]/\nconst SPACE = /\\s/\nconst LEADING_DASH = /^-/\n\nfunction isValidGitHubRef(ref: string): boolean {\n  return !!ref && !CONTROL.test(ref) && !SPACE.test(ref) && !LEADING_DASH.test(ref)\n}\n\nfunction isValidGitHubSource(source: string): boolean {\n  const hash = source.indexOf('#')\n  if (hash === -1) return true\n  const ref = source.slice(hash + 1)\n  return ref === '' ? false : isValidGitHubRef(ref)\n}","tryCatchPattern":"import { RegistryValidationError } from '@/src/registry/errors'\n\ntry {\n  resolveGitHubRegistrySource(source)\n} catch (e) {\n  if (e instanceof RegistryValidationError && e.code === 'VALIDATION_ERROR') {\n    logger.error(`Bad GitHub ref in '${source}': ${e.suggestion}`)\n    // prompt the user for a corrected ref\n  } else throw e\n}","preventionTips":["Never put whitespace or leading dashes in branch/tag names used as registry refs.","Prefer 40-character commit SHAs for reproducible registry sources.","Quote registry source strings in config files to avoid shell mangling.","Validate refs with `git ls-remote` before embedding them in components.json."],"tags":["registry","github","validation","ref","config"],"backgroundTag":null,"analyzedSha":"efac5987074af84ece57c367c6dd83387b967022","analyzedAt":"2026-08-12T05:00:50.218Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}