abhigyanpatwari/GitNexus · error · Error

contains characters not allowed in a git ref

Error message

contains characters not allowed in a git ref

What it means

Git ref syntax forbids several characters, so validateAutoSyncBranchName rejects branches containing any of ~ ^ : ? * [ \ before a git command is ever run. These characters would make the ref unresolvable or trigger glob/history syntax inside git, so the library fails at config parse time.

Source

Thrown at gitnexus/src/core/auto-sync/config.ts:338

  if (
    !repoName ||
    repoName === '.' ||
    repoName === '..' ||
    repoName === 'unknown' ||
    repoName.startsWith('-') ||
    !REMOTE_REPO_NAME_PATTERN.test(repoName)
  ) {
    throw new Error(
      'repository name must use only letters, digits, ".", "_", or "-" and must not be "unknown"',
    );
  }
}

export function validateAutoSyncBranchName(branch: string): void {
  if (!branch.trim()) throw new Error('must not be empty');
  if (/[\s\0-\x1f\x7f]/.test(branch))
    throw new Error('must not contain whitespace or control characters');
  if (/[~^:?*[\\]/.test(branch)) throw new Error('contains characters not allowed in a git ref');
  if (branch.startsWith('-')) throw new Error('must not start with "-"');
  if (branch.startsWith('/')) throw new Error('must not start with "/"');
  if (branch.includes('..')) throw new Error('must not contain ".."');
  if (branch.includes('`')) throw new Error('must not contain backticks');
  if (branch.endsWith('/') || branch.endsWith('.')) throw new Error('must not end with "/" or "."');
  if (branch.includes('//')) throw new Error('must not contain consecutive slashes');
  if (branch.includes('@{')) throw new Error('must not contain "@{"');
  if (
    branch
      .split('/')
      .some(
        (component) =>
          component.startsWith('.') || component.endsWith('.') || component.endsWith('.lock'),
      )
  )
    throw new Error('must not contain hidden, trailing-dot, or .lock path components');
}

View on GitHub (pinned to 0d1aed942f)

Solutions

  1. Use the plain branch/ref name without git revision syntax — drop ^, ~, :suffix.
  2. Replace backslashes with forward slashes for nested branch names: feature\\login → feature/login.
  3. If you meant a specific commit, configure the branch it lives on, not a revision expression.
  4. Validate locally with `git check-ref-format --branch '<name>'` before adding it to config.

Example fix

// before
branches:
  - "release~2"
// after
branches:
  - release
Defensive patterns

Strategy: validation

Validate before calling

const GIT_REF_BAD = /[~^:?*[\\]/;
function refCharsOk(b) {
  return typeof b === 'string' && !GIT_REF_BAD.test(b);
}
const bad = (cfg.branches ?? []).filter((b) => !refCharsOk(b));
if (bad.length) throw new Error(`branches contain git-ref-forbidden characters: ${JSON.stringify(bad)}`);

Try / catch

try {
  validateAutoSyncBranchName(branch);
} catch (e) {
  if (String(e.message).includes('characters not allowed in a git ref')) {
    log.error(`Branch '${branch}' uses ~^:?*[\\ which git refs forbid; use the plain branch name.`);
  }
  throw e;
}

Prevention

When it happens

Trigger: branches: ["feature:foo"], ["v1.0^"], ["release~2"], ["topic?"], ["fix[bug]"], or a Windows-style path like "feature\\login" in the auto-sync config.

Common situations: Copy-pasted tags with ^ or ~ suffixes (v1.2^ means 'parent of v1.2', not a branch); Windows users writing backslash-separated paths; query strings appended to branch names from URLs.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@0d1aed942f (2026-09-08). Data as JSON: /api/errors/12e80647be931b7b. Report an issue: GitHub.