abhigyanpatwari/GitNexus · warning · GitNexusRcError

: branch name must not be empty.

Error message

${source}: branch name must not be empty.

What it means

Crash-recovery cleanup: the main DB file is missing (fresh open fails fs.access(dbPath) with a missing-file error), but sidecar files (`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`) from an interrupted run still exist and would block fresh opens indefinitely. GitNexus removes each orphan sidecar; failure to remove one is logged with its errno because the subsequent LadybugDB open may still fail.

Solutions

  1. No action needed — removal enables the fresh open and the index rebuilds
  2. If the 'failed to remove orphan sidecar' companion warn appears, clear whatever holds the file (antivirus, another process) and rerun
  3. Use `gitnexus clean` rather than manual deletion so all sidecars go together
  4. Recurring occurrences mean something keeps interrupting runs at the same phase — check disk health and crash logs
Defensive patterns

Strategy: fallback

Validate before calling

import fs from 'node:fs/promises';
// when managing storage manually: remove sidecars only when the main DB is gone
const dbExists = await fs.access(dbPath).then(() => true, () => false);
if (!dbExists) {
  for (const s of [`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`]) {
    await fs.unlink(s).catch(() => {}); // ENOENT is fine
  }
}

Prevention

When it happens

Trigger: fs.access(dbPath) throws ENOENT while `.shadow` or `.wal.checkpoint` sidecars remain — typically after `gitnexus clean`/wipe was interrupted, the DB file was deleted manually, or a crash happened between DB-file removal and sidecar removal.

Common situations: An interrupted clean operation; users manually deleting the DB file but leaving companions; interrupted first-time init where the DB was never created but checkpoint sidecars appeared. After this warn, the index rebuilds from scratch.

Related errors

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

Appendix: source

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

  for (const ch of value) {
    const cp = ch.codePointAt(0);
    if (cp !== undefined && isHiddenOrControl(cp)) {
      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('..')) {

View on GitHub (pinned to 52924ef12c)