abhigyanpatwari/GitNexus · critical

LadybugDB WAL corruption detected at

Error message

LadybugDB WAL corruption detected at ${dbPath}. WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.
  Original error: ${msg.slice(0, 200)}

What it means

lbug-adapter.ts line 711 (schema creation): the first DDL write after opening the database triggers WAL replay; if the previous run was interrupted leaving a corrupt WAL, the native engine throws (matched by WAL_CORRUPTION_RE: 'corrupt(ed) wal', 'invalid wal record', 'wal…corrupt', 'checksum…wal'). Rather than logging a warning and continuing broken, the connection is closed cleanly, open-connection state is reset, and WAL_RECOVERY_SUGGESTION is surfaced: rebuild with `gitnexus analyze --force`.

Solutions

  1. Run `gitnexus analyze --force <repo-path>` to discard the corrupt WAL and rebuild the index
  2. If corruption recurs, find the interrupting cause: raise CI timeouts/memory, stop concurrent writers, add AV/sync exclusions for the storage dir
  3. Verify disk health if WAL corruption appears without any interrupted run

Example fix

# before
$ gitnexus serve   # 'WAL corruption detected' on open
# after
$ gitnexus analyze --force /path/to/repo
gitnexus serve
Defensive patterns

Strategy: retry

Try / catch

try {
  await withLbugDb(dbPath, run);
} catch (err) {
  const msg = err instanceof Error ? err.message : String(err);
  if (/corrupt(ed)?\s+wal|invalid\s+wal\s+record|wal.*corrupt|checksum.*wal/i.test(msg)) {
    // rebuild deterministically: `gitnexus analyze --force <repo>`, then retry the original operation once
  }
  throw err;
}

Prevention

When it happens

Trigger: A prior analyze/query was killed mid-write (OOM kill, SIGKILL, power loss) leaving a torn WAL; the WAL was truncated by disk-full; then any later command that opens the DB and issues DDL (analyze, or a writable serve path).

Common situations: CI runners being OOM-killed or timing out mid-analyze; laptops sleeping/crashing during indexing; antivirus or sync tools (Dropbox/OneDrive) mutating files in the storage dir; disk-full incidents.

Related errors

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

Appendix: source

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

      //   - "already exists": expected idempotent re-create on existing DBs
      //   - "could not set lock on file": LadybugDB v0.18.0 emits this on
      //     Windows when CREATE NODE TABLE runs against a path that was
      //     just opened (the WAL handle from a fresh Database briefly
      //     contests the table's first-write lock). The table is created
      //     anyway and any genuine cross-process lock contention surfaces
      //     on the next operation via withLbugDb's retry. Logging it here
      //     would just be noise in CI.
      //
      // WAL corruption: the first DDL write after DB open triggers WAL
      // replay — if the WAL file was left in a corrupt state by an
      // interrupted previous run, the native engine throws here. Rather
      // than logging a WARN and continuing in a broken state, close the
      // DB cleanly and surface an actionable error so the caller (serve,
      // MCP, analyze) can exit with a clear recovery message.
      if (isWalCorruptionError(err)) {
        await safeClose();
        resetOpenConnectionState();
        throw new Error(
          `LadybugDB WAL corruption detected at ${dbPath}. ${WAL_RECOVERY_SUGGESTION}\n` +
            `  Original error: ${msg.slice(0, 200)}`,
        );
      }
      if (isStorageVersionMismatchError(err)) {
        await safeClose();
        resetOpenConnectionState();
        throwIfStorageVersionMismatch(err);
      }
      if (!msg.includes('already exists') && !isDbBusyError(err) && !isReadOnlyDbError(err)) {
        logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
      }
    }
  }

  return null;
};

View on GitHub (pinned to ac9a4e9abd)