LadybugDB WAL corruption detected for ${repoId}. WAL corrupt

Error message

LadybugDB WAL corruption detected for ${repoId}. WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index. (${retryErr instanceof Error ? retryErr.message : String(retryErr)})

What it means

Thrown when the WAL corruption recovery path succeeds in quarantining the .wal file (rename works) but the subsequent reopen of the database (openReadOnlyDatabase) itself fails. The recovery chain: open fails with WAL corruption → tryQuarantineAndReopen renames .wal successfully → openReadOnlyDatabase throws → this error wraps the reopen failure. WAL_RECOVERY_SUGGESTION is 'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.' The error includes the retry error message for diagnostics.

Source

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

        shared = { db, refCount: 0, ftsLoaded: false, dbIdentity: await statDbIdentity(dbPath) };
        dbCache.set(dbPath, shared);
        break;
      } catch (err: any) {
        lastError = err instanceof Error ? err : new Error(String(err));

        if (isWalCorruptionError(lastError)) {
          try {
            const db = await tryQuarantineAndReopen(dbPath, repoId);
            shared = {
              db,
              refCount: 0,
              ftsLoaded: false,
              dbIdentity: await statDbIdentity(dbPath),
            };
            dbCache.set(dbPath, shared);
            break;
          } catch (retryErr) {
            throw new Error(
              `LadybugDB WAL corruption detected for ${repoId}. ${WAL_RECOVERY_SUGGESTION} ` +
                `(${retryErr instanceof Error ? retryErr.message : String(retryErr)})`,
            );
          }
        }

        if (
          lastError.message.startsWith('LadybugDB checkpoint sidecar is missing') ||
          lastError.message.startsWith('LadybugDB checkpoint sidecar is present but unreachable') ||
          lastError.message.startsWith('GitNexus could not move the LadybugDB WAL sidecar') ||
          isMissingShadowSidecarError(lastError)
        ) {
          throw lastError;
        }

        const isLockError =
          lastError.message.includes('Could not set lock') ||
          /\block(\b|ed|ing)/i.test(lastError.message);

View on GitHub (pinned to d540b00184)

Solutions

Run `gitnexus analyze --force` to rebuild the index from scratch — this is the recommended action in the error message
Read the wrapped retryErr message to understand the secondary failure (e.g. checkpoint sidecar missing) — this may indicate a deeper filesystem issue
If `--force` also fails, check filesystem health (fsck/disk utility) — the storage volume may have hardware errors
Stop all GitNexus processes before rebuilding to ensure exclusive file access
As a last resort, delete the .gitnexus/ directory entirely and re-run `gitnexus analyze`

Defensive patterns

Strategy: fallback

Try / catch

try {
  const db = await tryQuarantineAndReopen(dbPath, repoId);
} catch (e) {
  if (e instanceof Error && e.message.includes('WAL corruption detected')) {
    // Quarantine succeeded but reopen failed — force full rebuild
    logger.error('WAL quarantine reopen failed — run `gitnexus analyze --force`');
  }
  throw e;
}

Prevention

Run `gitnexus analyze --force` as the primary recovery for persistent WAL corruption
Stop all GitNexus processes before rebuilding to ensure clean file access
Check filesystem health (fsck) if corruption recurs after rebuild — hardware errors may be the root cause
Keep regular backups of the .gitnexus/ directory for large repos to avoid full re-analyze

When it happens

Trigger: Opening a read-only LadybugDB DB via the pool adapter where the WAL is corrupt AND the DB file itself is also damaged (so even without the WAL, the open fails). The quarantine succeeds but the shadow sidecar or checkpoint data is also missing/corrupt, so the reopened database throws a different error — perhaps a missing checkpoint sidecar, a corrupt DB header, or a schema mismatch.

Common situations: Severe index corruption where both the WAL and the main DB file are damaged (e.g. after a power failure, filesystem crash, or force-kill during checkpoint); a LadybugDB version upgrade that changed the DB format so the old file can't be opened even without WAL; a partially-deleted .gitnexus/ directory where some files were removed but not others.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/836f990bda214cd6. Report an issue: GitHub.