GitNexus: unable to verify main DB file before orphan sideca

Error message

GitNexus: unable to verify main DB file before orphan sidecar cleanup (${code ?? 'UNKNOWN'}); skipping cleanup: ${summarizeError(err)}

What it means

Preflight calls fs.access(dbPath) to decide whether orphan-sidecar cleanup is safe; the access failed with an error other than ENOENT (e.g. EACCES on a parent directory, ELOOP, EIO). Because the code cannot prove the main DB file's state, it skips cleanup entirely and warns — the open that follows may then trip over sidecars it dared not remove.

Source

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

          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,
        allowQuarantine: true,
      });

      const opened = await openLbugConnection(lbug, dbPath);
      db = opened.db;
      conn = opened.conn;
      currentDbReadOnly = false;

View on GitHub (pinned to 0d1aed942f)

Solutions

Verify reachability of every path component: `namei -l <dbPath>` shows where permission fails; chmod the offending directory.
Fix or remove broken symlinks in the .gitnexus path after moving a repo.
Re-run once transient FS faults clear; if it recurs on network storage, move the DB to local disk.

Defensive patterns

Strategy: validation

Validate before calling

// Before analyze: every path component must be searchable by this user
import { access } from 'node:fs/promises';
for (let dir = path.dirname(dbPath); ; dir = path.dirname(dir)) {
  await access(dir, fsConstants.X_OK);
  if (dir === path.dirname(dir)) break;
}

Prevention

Run namei -l on the DB path when opens behave oddly — it pinpoints the denied component.
Avoid symlink loops / stale links in .gitnexus paths after repo moves.
Prefer local disk over NFS/overlay for the index DB.

When it happens

Trigger: A path component of dbPath lacks execute/search permission, dbPath is a symlink loop, or the filesystem returns EIO; anything except a clean 'file missing' answer. The else-branch fires exactly when isMissingFileError(err) is false.

Common situations: DB directories with restrictive modes (700 owned by another user), broken symlinks in the path after repo moves, NFS/overlayfs transient faults in containers, SELinux/AppArmor denials.

Related errors

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