abhigyanpatwari/GitNexus · error · GitNexusRcError

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

Error message

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

What it means

Thrown by validateBranchName() when the trimmed branch name exceeds BRANCH_MAX_LENGTH (255 characters). Real git refs are short; a value over 255 bytes is almost certainly a paste error or an injection attempt, and git itself enforces similar limits.

Source

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

      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('..')) {
    throw new GitNexusRcError(`${source}: branch name must not contain "..".`);
  }
  // Git permits a backtick in a ref, but the branch is embedded inside a

View on GitHub (pinned to d540b00184)

Solutions

1. Shorten the branch name to a real git ref (typically under 60 characters).
2. If the long value came from a script, check the source variable for a concatenation bug.
3. Omit the override and let auto-detect resolve the branch.

Example fix

// before
{ "defaultBranch": "feature/very-long-description-continued-with-...-255+-chars" }

// after
{ "defaultBranch": "feature/short-name" }

function checkBranchLength(name: string, max = 255): void {
  if (name.trim().length > max) {
    throw new Error(`branch name too long (${name.length} > ${max})`);
  }
}

function isBranchLengthOk(name: string, max = 255): boolean {
  return typeof name === 'string' && name.trim().length <= max;
}

When it happens

Trigger: Passing a branch name longer than 255 characters, e.g. a long URL, a base64 blob, or a multi-line string pasted by accident.

Common situations: Pasting the wrong clipboard contents into --default-branch; a config value that accidentally captured a multi-line block; a generated name that concatenated several identifiers.

Related errors

• ${source}: branch name must not be empty.
• ${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/fbdf839cadbd7801. Report an issue: GitHub.