abhigyanpatwari/GitNexus · error · InvalidBranchError

: branch name must not be empty.

Error message

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

What it means

validateBranchName first trims the value and rejects it if nothing remains, throwing InvalidBranchError '<source>: branch name must not be empty.' The library requires a concrete branch name because an empty ref can never resolve in git and usually signals a missing or unset option.

Solutions

  1. Supply an actual branch name at the call site (flag, config field, or variable).
  2. Add a guard before the call: if (!branch?.trim()) fail early with your own actionable message naming the missing option.
  3. Check the config/env path that produced the empty string and set a correct default.

Example fix

// before
const branch = process.env.BRANCH ?? '';
validateBranchName(branch, 'deploy');
// after
const branch = process.env.BRANCH;
if (!branch || !branch.trim()) throw new Error('BRANCH env var must be set to a branch name');
validateBranchName(branch, 'deploy');
Defensive patterns

Strategy: validation

Validate before calling

if (typeof branch !== 'string' || !branch.trim()) {
  throw new Error('Branch name is required: pass --branch or set the branch config field.');
}

Type guard

const isNonEmptyBranch = (v: unknown): v is string =>
  typeof v === 'string' && v.trim().length > 0;

Try / catch

try {
  branch = validateBranchName(input, 'deploy');
} catch (e) {
  if (e instanceof InvalidBranchError && /must not be empty/.test(e.message)) {
    throw new Error('No branch provided: set --branch or BRANCH env var.');
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling validateBranchName('' or ' ', source) — e.g. a CLI flag or config field for a branch was never set, or an empty environment variable was passed through.

Common situations: Missing --branch flag with no default; unset BRANCH env var interpolated into an empty string; config file with `branch: ""`; a caller passing an unpopulated variable before assignment.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at gitnexus/src/core/git-ref.ts:59

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

/**
 * Validate a user-supplied branch name. Returns the trimmed name or throws
 * {@link InvalidBranchError}. 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 InvalidBranchError(`${source}: branch name must not be empty.`);
  }
  if (trimmed.length > BRANCH_MAX_LENGTH) {
    throw new InvalidBranchError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
  }
  assertNoHiddenChars(trimmed, source);
  if (/\s/.test(trimmed)) {
    throw new InvalidBranchError(`${source}: branch name must not contain whitespace.`);
  }
  // git ref-name rules (subset): reject characters git itself forbids in refs.
  if (/[~^:?*[\\]/.test(trimmed)) {
    throw new InvalidBranchError(
      `${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`,
    );
  }
  if (trimmed.startsWith('-')) {
    throw new InvalidBranchError(`${source}: branch name must not start with "-".`);
  }
  // Force-refspec prefix (`git fetch origin +main` / `+refs/heads/main:…`).

View on GitHub (pinned to ac9a4e9abd)