{"record":{"id":"6986f691d9eea012","repo":"abhigyanpatwari/GitNexus","slug":"err-message-invalidbrancherror-rethrown-as-gitnexusrcerror","errorCode":null,"errorMessage":"err.message (InvalidBranchError rethrown as GitNexusRcError for .gitnexusrc)","messagePattern":"err\\.message \\(InvalidBranchError rethrown as GitNexusRcError for \\.gitnexusrc\\)","errorType":"validation","errorClass":"GitNexusRcError","httpStatus":null,"severity":"error","filePath":"gitnexus/src/cli/analyze-config.ts","lineNumber":169,"sourceCode":"    if (cp !== undefined && isHiddenOrControl(cp)) {\n      throw new GitNexusRcError(\n        `${source}: value contains control or hidden/bidirectional characters, which are not allowed.`,\n      );\n    }\n  }\n};\n\n/**\n * Validate a user-supplied branch name (from CLI or `.gitnexusrc`). Returns the\n * trimmed name or throws {@link GitNexusRcError}. Rules live in\n * `core/git-ref.ts`; this wrapper keeps the CLI / `.gitnexusrc` error type.\n */\nexport function validateBranchName(value: string, source: string): string {\n  try {\n    return validateBranchNameCore(value, source);\n  } catch (err) {\n    if (err instanceof InvalidBranchError) {\n      throw new GitNexusRcError(err.message);\n    }\n    throw err;\n  }\n}\n\n/**\n * Best-effort validation for an auto-detected branch (from git). Never throws —\n * returns `undefined` for anything unusable so the resolver falls back to the\n * next precedence tier.\n */\nexport function sanitizeDetectedBranch(value: string | null | undefined): string | undefined {\n  if (!value) return undefined;\n  try {\n    return validateBranchName(value, 'detected branch');\n  } catch {\n    return undefined;\n  }\n}","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/cli/analyze-config.ts#L151-L187","documentation":"validateBranchName in analyze-config.ts validates a branch name coming from a .gitnexusrc file (or defaults). If the core validation fails with InvalidBranchError, it is rethrown as a GitNexusRcError so config-file problems surface as configuration errors rather than generic validation failures. It means the branch string in your GitNexus config is not an acceptable git branch name.","triggerScenarios":"Calling validateBranchName (directly or via sanitizeDetectedBranch, normalizeValue, resolveDefaultBranch, or the branch accessor) with a value read from .gitnexusrc that fails git ref-name rules — e.g. contains spaces, '..', a leading/trailing slash, invalid characters like '~' or '^', or is empty.","commonSituations":"A typo in the `branch` key of .gitnexusrc, quoting errors leaving stray whitespace, pasting a refspec like `refs/heads/main` or a range like `main..dev` instead of a plain branch name, or tooling writing an empty branch value.","solutions":["Open .gitnexusrc and fix the `branch` value to a valid git branch name (no spaces, '..', leading '-', control characters, or trailing slashes).","Run `git branch --list <name>` or `git check-ref-format --branch <name>` to confirm the name is a legal ref before saving it.","If the value was inherited from another tool (CI, docs), replace the refspec/range expression with the bare branch name, e.g. `main` not `refs/heads/main`.","If the invalid value comes from an environment/CI variable injected into the config, correct or unset that variable."],"exampleFix":"// .gitnexusrc before\nbranch = \"release/v1..v2\"\n// .gitnexusrc after\nbranch = \"release-v1-v2\"","handlingStrategy":"validation","validationCode":"function isValidBranchName(name) {\n  if (typeof name !== 'string' || !name.trim()) return false;\n  return !/[~^:?*\\[\\]\\\\\\s]/.test(name) && !name.startsWith('-') &&\n    !name.includes('..') && !name.startsWith('/') && !name.endsWith('/') &&\n    !name.includes('//');\n}\n// validate the `branch` field in .gitnexusrc before handing it to GitNexus","typeGuard":"const isBranchName = (v: unknown): v is string =>\n  typeof v === 'string' && v.trim().length > 0 && !/[~^:?*\\[\\]\\\\\\s]/.test(v) &&\n  !v.includes('..');","tryCatchPattern":"try {\n  await gitnexus.analyze({ branch: cfg.branch });\n} catch (err) {\n  if (err instanceof GitNexusRcError) {\n    console.error(`Invalid branch in .gitnexusrc: ${err.message}`);\n    process.exitCode = 2;\n  } else throw err;\n}","preventionTips":["Validate branch values with `git check-ref-format --branch` before writing them to .gitnexusrc.","Never paste refspecs (refs/heads/x, a..b) into the branch config field.","Keep .gitnexusrc in version control with a lint check that validates its branch field.","Trim and quote-check values generated by scripts injecting env vars into the config."],"tags":["config","git","validation","branch-name"],"backgroundTag":"invalid-config-value","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-09-15T23:29:44.066Z","contentChangedAt":"2026-09-15T23:29:44.066Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}