abhigyanpatwari/GitNexus · warning

GitNexus: failed to reclaim missing-shadow WAL quarantines:

Error message

GitNexus: failed to reclaim missing-shadow WAL quarantines: ${summarizeError(err)}

What it means

During DB open preflight, GitNexus tried to restore WAL files quarantined by a previous crash (cleanQuarantinedMissingShadowWals) and the reclaim threw. Deliberately non-fatal — a transient EBUSY must not block DB startup — so quarantined WALs stay on disk and any data they held remains unreclaimed until a later run succeeds.

Source

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

      // Reclaim missing-shadow WAL quarantines from a PRIOR crash (#2637).
      // LadybugDB renames an unrecoverable WAL aside as
      // `${dbPath}.wal.missing-shadow.<ts>-<rand>` (quarantineWalForMissingShadow)
      // instead of deleting it. Once quarantined it is permanently detached from
      // the live store and never reopened, so reclaiming it is safe regardless of
      // whether the main DB file exists this run — unlike the orphan-sidecar
      // cleanup below, this must NOT be gated on "main DB missing": a quarantine
      // event and a healthy main DB are independent facts. Never let a reclaim
      // failure (e.g. a transient EBUSY from an antivirus scan) block DB startup.
      if (!sidecarPreflightDisabled()) {
        try {
          const reclaimed = await cleanQuarantinedMissingShadowWals(dbPath);
          for (const file of reclaimed) {
            logger.warn(
              `GitNexus: reclaimed quarantined WAL ${path.basename(file)} from a prior crash`,
            );
          }
        } catch (err) {
          logger.warn(
            `GitNexus: failed to reclaim missing-shadow WAL quarantines: ${summarizeError(err)}`,
          );
        }
      }

      // Crash-recovery cleanup: if the main DB file is missing, stale sidecars
      // from an interrupted run can block fresh opens indefinitely.
      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(

View on GitHub (pinned to 0d1aed942f)

Solutions

  1. Simply retry the analyze/serve run — transient EBUSY typically clears and the next preflight reclaims successfully.
  2. Add the repo's .gitnexus directory to antivirus exclusions (the code calls this scenario out by name).
  3. If it persists, inspect the quarantine sidecar files next to the DB and restore/remove them manually while nothing else runs.
  4. As a diagnostic escape hatch only, GITNEXUS_DISABLE_LBUG_SIDECAR_PREFLIGHT=1 skips preflight — use it to confirm the diagnosis, not as a permanent fix.
Defensive patterns

Strategy: retry

Try / catch

// Reclaim failure is transient-tolerant by design: retry the open
for (let attempt = 1; attempt <= 3; attempt++) {
  try { return await initLbug(dbPath); }
  catch (err) {
    if (attempt === 3 || !isTransientFsError(err)) throw err;
    await sleep(500 * attempt); // EBUSY from AV scans usually clears
  }
}

Prevention

When it happens

Trigger: ensureLbugInitialized opens a DB whose directory contains quarantined WAL files from a prior crash; the reclaim (rename/copy back) fails with EBUSY, EACCES, EXDEV, or an I/O error. The code explicitly notes antivirus scans as a known transient source.

Common situations: Windows machines with real-time antivirus scanning the .gitnexus directory right at open; quarantined files on network/EXDEV layouts; runs immediately after a crashed process whose handles the OS has not released; permission drift after container restarts.

Related errors

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