abhigyanpatwari/GitNexus · error · Error

must not start with "/"

Error message

must not start with "/"

What it means

Git refs must not begin with '/', so validateAutoSyncBranchName rejects branches starting with a slash. A leading slash would also produce a malformed ref path (refs/heads//name) and is reserved syntax, so the library throws at parse time.

Source

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

    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');
}

export function parseDurationMs(value: unknown): number {
  if (typeof value === 'number') return value * 1_000;

View on GitHub (pinned to 0d1aed942f)

Solutions

  1. Remove the leading slash and use the bare branch name: /main → main.
  2. Do not include refs/heads/ — auto-sync expects the short branch name only.
  3. If the branch is nested, keep internal slashes but not a leading one: feature/login is valid.

Example fix

// before
branches:
  - "/main"
// after
branches:
  - main
Defensive patterns

Strategy: validation

Validate before calling

function noLeadingSlash(b) {
  return typeof b === 'string' && !b.startsWith('/');
}
function normalizeBranch(b) {
  return b.replace(/^refs\/heads\//, '').replace(/^\/+/, '');
}
const branches = (cfg.branches ?? []).map(normalizeBranch);
if (!branches.every(noLeadingSlash)) throw new Error('branches must not start with "/"');

Try / catch

try {
  validateAutoSyncBranchName(branch);
} catch (e) {
  if (String(e.message).includes('must not start with "/"')) {
    log.error(`Strip the leading slash / refs/heads/ prefix from '${branch}'.`);
  }
  throw e;
}

Prevention

When it happens

Trigger: branches: ["/main"] or ["/feature/login"]; the leading 'refs/heads/' prefix accidentally left on: ["refs/heads/main"] is fine, but a half-stripped ["/heads/main"] is not; copy-paste that included a path separator from a URL.

Common situations: Developers pasting full ref paths or URLs like https://host/owner/repo/tree/main and keeping the slash; scripts that join paths and prepend '/' by mistake.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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