abhigyanpatwari/GitNexus · error · GitNexusRcError

err.message (InvalidBranchError rethrown as GitNexusRcError…

Error message

err.message (InvalidBranchError rethrown as GitNexusRcError for .gitnexusrc)

What it means

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.

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.

Example fix

// .gitnexusrc before
branch = "release/v1..v2"
// .gitnexusrc after
branch = "release-v1-v2"

Defensive patterns

Strategy: validation

Validate before calling

function isValidBranchName(name) {
  if (typeof name !== 'string' || !name.trim()) return false;
  return !/[~^:?*\[\]\\\s]/.test(name) && !name.startsWith('-') &&
    !name.includes('..') && !name.startsWith('/') && !name.endsWith('/') &&
    !name.includes('//');
}
// validate the `branch` field in .gitnexusrc before handing it to GitNexus

Type guard

const isBranchName = (v: unknown): v is string =>
  typeof v === 'string' && v.trim().length > 0 && !/[~^:?*\[\]\\\s]/.test(v) &&
  !v.includes('..');

Try / catch

try {
  await gitnexus.analyze({ branch: cfg.branch });
} catch (err) {
  if (err instanceof GitNexusRcError) {
    console.error(`Invalid branch in .gitnexusrc: ${err.message}`);
    process.exitCode = 2;
  } else throw err;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-09-15). Data as JSON: /api/errors/6986f691d9eea012. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/cli/analyze-config.ts:169

    if (cp !== undefined && isHiddenOrControl(cp)) {
      throw new GitNexusRcError(
        `${source}: value contains control or hidden/bidirectional characters, which are not allowed.`,
      );
    }
  }
};

/**
 * Validate a user-supplied branch name (from CLI or `.gitnexusrc`). Returns the
 * trimmed name or throws {@link GitNexusRcError}. Rules live in
 * `core/git-ref.ts`; this wrapper keeps the CLI / `.gitnexusrc` error type.
 */
export function validateBranchName(value: string, source: string): string {
  try {
    return validateBranchNameCore(value, source);
  } catch (err) {
    if (err instanceof InvalidBranchError) {
      throw new GitNexusRcError(err.message);
    }
    throw err;
  }
}

/**
 * Best-effort validation for an auto-detected branch (from git). Never throws —
 * returns `undefined` for anything unusable so the resolver falls back to the
 * next precedence tier.
 */
export function sanitizeDetectedBranch(value: string | null | undefined): string | undefined {
  if (!value) return undefined;
  try {
    return validateBranchName(value, 'detected branch');
  } catch {
    return undefined;
  }
}

View on GitHub (pinned to ac9a4e9abd)