abhigyanpatwari/GitNexus · error · GitNexusRcError

${source}: branch name must not be empty.

Error message

${source}: branch name must not be empty.

What it means

Thrown by validateBranchName() when the trimmed branch name is the empty string. Branch names flow into the generated AGENTS.md/CLAUDE.md regression example as a git checkout command, so an empty value would produce a broken command with no signal to the user.

Source

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

  for (const ch of value) {
    const cp = ch.codePointAt(0);
    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}. Conservative but accepts the
 * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
 */
export function validateBranchName(value: string, source: string): string {
  const trimmed = value.trim();
  if (!trimmed) {
    throw new GitNexusRcError(`${source}: branch name must not be empty.`);
  }
  if (trimmed.length > BRANCH_MAX_LENGTH) {
    throw new GitNexusRcError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
  }
  assertNoHiddenChars(trimmed, source);
  if (/\s/.test(trimmed)) {
    throw new GitNexusRcError(`${source}: branch name must not contain whitespace.`);
  }
  // git ref-name rules (subset): reject characters git itself forbids in refs.
  if (/[~^:?*[\\]/.test(trimmed)) {
    throw new GitNexusRcError(
      `${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`,
    );
  }
  if (trimmed.startsWith('-')) {
    throw new GitNexusRcError(`${source}: branch name must not start with "-".`);
  }
  if (trimmed.includes('..')) {

View on GitHub (pinned to d540b00184)

Solutions

1. Omit the flag/keys entirely to let the resolver fall through to auto-detect or the 'main' fallback.
2. Pass a real branch name that matches your repo's default.
3. If deriving from git, fall back to the detected origin/HEAD rather than an empty string.

Example fix

# before
gitnexus analyze --default-branch ""

# after (omit the flag)
gitnexus analyze

function resolveBranch(cli?: string, config?: string, detected?: string | null): string {
  const candidates = [cli, config, detected].filter((v) => typeof v === 'string' && v.trim() !== '');
  return candidates.length ? candidates[0]! : 'main';
}

function isNonEmptyBranch(value: unknown): value is string {
  return typeof value === 'string' && value.trim().length > 0;
}

When it happens

Trigger: Passing --default-branch '' (empty), --default-branch ' ' (whitespace only), or a .gitnexusrc with "defaultBranch": "".

Common situations: A CI job that sets DEFAULT_BRANCH from an env var that is sometimes empty; clearing a branch override by passing an empty string rather than omitting the flag; a config template with a placeholder that was never filled.

Related errors

• ${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}
• ${source}: branch name must not contain whitespace.
• ${source}: branch name contains characters not allowed in a
• ${source}: branch name must not start with "-".
• ${source}: branch name must not contain "..".

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/424e29d413f9a1e7. Report an issue: GitHub.