abhigyanpatwari/GitNexus · error · InvalidBranchError

: branch name is too long (max ).

Error message

${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).

What it means

validateBranchName enforces a maximum branch-name length (BRANCH_MAX_LENGTH) and throws InvalidBranchError '<source>: branch name is too long (max N).' when the trimmed value exceeds it. Overlong refs cause problems with git plumbing, filesystem path limits (.git/refs files), and downstream tools.

Solutions

  1. Shorten the branch name to at most BRANCH_MAX_LENGTH characters (trim descriptors, use IDs instead of prose).
  2. Programmatically truncate or slugify generated names before validation, keeping a unique suffix.
  3. Check the check the length limit value via BRANCH_MAX_LENGTH and enforce it in your name generator.
  4. Use a shorter naming convention/prefix for automated branches.

Example fix

// before
const branch = `${prefix}/${ticket}/${Date.now()}/${user}/${slug}`;
validateBranchName(branch, 'ci');
// after
let branch = `${prefix}/${ticket}/${slug}`;
if (branch.length > BRANCH_MAX_LENGTH) branch = branch.slice(0, BRANCH_MAX_LENGTH);
validateBranchName(branch, 'ci');
Defensive patterns

Strategy: validation

Validate before calling

import { BRANCH_MAX_LENGTH } from './git-ref';
if (name.length > BRANCH_MAX_LENGTH) {
  name = name.slice(0, BRANCH_MAX_LENGTH);
}

Type guard

const isWithinBranchLength = (v: string): boolean => v.length <= BRANCH_MAX_LENGTH;

Try / catch

try {
  branch = validateBranchName(generated, 'ci');
} catch (e) {
  if (e instanceof InvalidBranchError && /too long/.test(e.message)) {
    branch = validateBranchName(truncateWithHash(generated, BRANCH_MAX_LENGTH), 'ci');
  } else throw e;
}

Prevention

When it happens

Trigger: Calling validateBranchName with a trimmed value whose length exceeds BRANCH_MAX_LENGTH — typically auto-generated names like long ticket slugs, timestamps, hashes, or AI-generated descriptive branch names concatenated together.

Common situations: Build systems that concatenate prefix + ticket ID + timestamp + user into a branch; CI-generated release branch names; migrating repos with extremely long legacy branch names.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

      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:…`).
  // Rejected here so neither the CLI nor HTTP can pass a force-update refspec
  // through as a "branch" (#3199 review, defense in depth).
  if (trimmed.startsWith('+')) {

View on GitHub (pinned to ac9a4e9abd)