abhigyanpatwari/GitNexus · warning · GitNexusRcError

: branch name must not start with "-".

Error message

${source}: branch name must not start with "-".

What it means

On Windows, toNativeSafePath converts non-ASCII paths to an ASCII-safe form via 8.3 short names, then a junction fallback. Junctions cannot be created from a worker thread (main-thread-only fallback), so when the 8.3 short-name conversion also fails inside a worker, GitNexus warns and returns the original non-ASCII path. LadybugDB may then fail to open files under that path.

Solutions

1. Enable 8.3 short names on the volume: fsutil 8dot3name set 0 (then re-create files so short names generate)
2. Move the repo/storage path to pure ASCII (e.g. C:\src\repo)
3. Set GITNEXUS storage location to an ASCII directory if the repo itself cannot move
4. Check whether short names exist for the path: fsutil file queryshortname <file>

const NON_ASCII_RE = /[^\x00-\x7f]/;
// before spawning workers: resolve the ASCII-safe path ON THE MAIN THREAD
// (junction fallback is main-thread-only) and hand workers the safe path
export const preResolveSafePath = (p: string): string => {
  if (process.platform !== 'win32' || !NON_ASCII_RE.test(p)) return p;
  return toNativeSafePath(p); // main thread: 8.3 short name or junction applies
};

const isAsciiPath = (p: string): boolean => !/[^\x00-\x7f]/.test(p);

When it happens

Trigger: process.platform === 'win32', NON_ASCII_RE matches the path, tryShortPath returns null (8.3 names disabled on the volume), and !isMainThread — the junction branch is unreachable, so the raw path is returned with this warn.

Common situations: Repos cloned under CJK/Unicode user profiles (C:\Users\名前\...) on volumes where `fsutil 8dot3name` is disabled; worker threads handling DB/CSV paths inherited from a non-ASCII storage location. Frequently followed by 'Cannot open file.' errors from LadybugDB.

Related errors

• : branch name must not contain "..".
• argument contains a double quote, unsafe for the Windows…
• argument contains NUL/CR/LF, unsafe for the Windows shell
• Could not remove the shadowed branch sub-index; keeping its…
• Failed to remove the LadybugDB index files — still present…

AI-assisted analysis of abhigyanpatwari/GitNexus@52924ef12c (2026-08-20). Data as JSON: /api/errors/b89624d091477dad. Report an issue: GitHub.

Appendix: source

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

  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
  // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression
  // example, where a backtick would close the span early and let the rest of
  // the template render as instruction text. Reject it at this single
  // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via
  // sanitizeDetectedBranch) are covered (#1996 tri-review P1).
  if (trimmed.includes('`')) {
    throw new GitNexusRcError(
      `${source}: branch name must not contain a backtick (it would break the generated Markdown).`,
    );
  }
  return trimmed;
}

View on GitHub (pinned to 52924ef12c)