abhigyanpatwari/GitNexus · warning

GitNexus: failed to remove orphan sidecar ${path.basename(si

Error message

GitNexus: failed to remove orphan sidecar ${path.basename(sidecar)} (${code ?? 'UNKNOWN'}) while main DB file is missing; LadybugDB open may still fail: ${summarizeError(err)}

What it means

The main DB file is missing (fs.access threw ENOENT), so preflight tries to remove orphaned sidecar files (`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`) that would otherwise block a fresh open. One of the unlinks failed with a non-ENOENT error; the warn explicitly says the LadybugDB open that follows may still fail because of the leftover sidecar.

Source

Thrown at gitnexus/src/core/lbug/lbug-adapter.ts:886

      try {
        await fs.access(dbPath);
      } catch (err) {
        if (isMissingFileError(err)) {
          // `.shadow` is documented by LadybugDB checkpointing and `.wal.checkpoint`
          // was observed in the #1618 crash loop that motivated this recovery path.
          const orphanSidecars = [`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`];
          for (const sidecar of orphanSidecars) {
            try {
              await fs.unlink(sidecar);
              logger.warn(
                `GitNexus: removed orphan sidecar ${path.basename(sidecar)} (no main DB file present)`,
              );
            } catch (err) {
              if (isMissingFileError(err)) {
                continue;
              }
              const code = extractErrnoCode(err);
              logger.warn(
                `GitNexus: failed to remove orphan sidecar ${path.basename(sidecar)} (${code ?? 'UNKNOWN'}) while main DB file is missing; LadybugDB open may still fail: ${summarizeError(err)}`,
              );
            }
          }
        } else {
          const code = extractErrnoCode(err);
          logger.warn(
            `GitNexus: unable to verify main DB file before orphan sidecar cleanup (${code ?? 'UNKNOWN'}); skipping cleanup: ${summarizeError(err)}`,
          );
        }
      }

      // Ensure parent directory exists
      const parentDir = path.dirname(dbPath);
      await fs.mkdir(parentDir, { recursive: true });
      await preflightLbugSidecars(dbPath, {
        mode: 'write',
        logger,

View on GitHub (pinned to 0d1aed942f)

Solutions

1. Manually delete both sidecars while gitnexus is not running: `rm -f <dbPath>.shadow <dbPath>.wal.checkpoint`, then retry.
2. Close any process holding the files open (lsof/fuser on Unix, Resource Monitor on Windows) and retry.
3. Fix ownership/permissions on the DB directory so the running user can unlink.
4. Retry once — EBUSY from a scan is often transient.

Example fix

# before: 'failed to remove orphan sidecar ... LadybugDB open may still fail'
rm -f .gitnexus/db.lbug .gitnexus/db.lbug.shadow .gitnexus/db.lbug.wal.checkpoint
npx gitnexus analyze   # after: clean open with fresh DB and sidecars

// Before open: when the main DB is gone, clear ALL sidecars yourself
import { unlink } from 'node:fs/promises';
const sidecars = [`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`, `${dbPath}.wal`];
await Promise.allSettled(sidecars.map((f) => unlink(f))); // preflight then opens cleanly

When it happens

Trigger: Someone deleted the main DB file (or a crashed run left only sidecars); then `fs.unlink(sidecar)` hits EPERM/EACCES, EBUSY, or EISDIR-style errors. Startup continues, but the subsequent engine open can error out on the stale sidecar pair.

Common situations: Manual cleanup that deleted the DB but not its sidecars; Windows file handles held by antivirus/indexers; NFS silly-rename semantics; sidecar directories created by mistake at the sidecar path.

Related errors

• GitNexus: manual WAL checkpoint failed after retries
• ${source} must be a string branch name.
• GitNexus: failed to reclaim missing-shadow WAL quarantines:
• ${source}: value contains control or hidden/bidirectional ch
• ${source}: branch name must not be empty.

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