LadybugDB WAL corruption detected for ${repoId}. Run `gitnex

Error message

LadybugDB WAL corruption detected for ${repoId}. Run `gitnexus analyze` to rebuild the index. (quarantine failed)

What it means

Thrown by tryQuarantineAndReopen when fs.rename of the .wal file to a quarantine name fails. This function is the WAL corruption recovery path: the initial DB open detected a corrupt WAL (matched by isWalCorruptionError), and the remedy is to rename the .wal aside so LadybugDB can open without replaying corrupt WAL records. If the rename itself fails (permission denied, file locked by another process, or the .wal file doesn't exist), quarantine is impossible and the error propagates. The quarantined WAL is named with a timestamp + random suffix.

Source

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

  } catch (err) {
    if (db) await db.close().catch(() => {});
    throw err;
  } finally {
    restoreStdout();
  }
}

/**
 * Quarantine the .wal file and retry opening the database.
 * Used when the initial open fails with a WAL corruption error.
 */
async function tryQuarantineAndReopen(dbPath: string, repoId: string): Promise<lbug.Database> {
  const walPath = dbPath + '.wal';
  const quarantineName = `${walPath}.corrupt.${Date.now()}-${Math.random().toString(36).slice(2)}`;
  try {
    await fs.rename(walPath, quarantineName);
  } catch {
    throw new Error(
      `LadybugDB WAL corruption detected for ${repoId}. ` +
        `Run \`gitnexus analyze\` to rebuild the index. (quarantine failed)`,
    );
  }
  realStderrWrite(
    `GitNexus: LadybugDB WAL quarantined for ${repoId}; graph may be stale. ` +
      `Run \`gitnexus analyze\` to rebuild the index.\n`,
  );
  return await openReadOnlyDatabase(dbPath);
}

/** Deduplicates concurrent initLbug calls for the same repoId */
const initPromises = new Map<string, Promise<void>>();

/**
 * Initialize (or reuse) a Database + connection pool for a specific repo.
 * Retries on lock errors (e.g., when `gitnexus analyze` is running).
 *

View on GitHub (pinned to d540b00184)

Solutions

Stop all GitNexus processes (serve, MCP) that may hold the .wal file, then re-run `gitnexus analyze` to rebuild the index from scratch
Run `gitnexus analyze --force` to force a full rebuild — this recreates the DB and WAL cleanly
Check filesystem permissions on the .gitnexus/ storage directory — the GitNexus process needs read/write access
If on a read-only mount, remount read-write or point GitNexus storage to a writable location
Use `lsof <repo>.wal` to find and kill any process holding the file

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify the WAL file is writable before attempting quarantine
import { access, constants } from 'fs/promises';
async function canQuarantineWal(walPath: string): Promise<boolean> {
  try {
    await access(walPath, constants.W_OK);
    return true;
  } catch {
    return false;
  }
}

Try / catch

try {
  const db = await tryQuarantineAndReopen(dbPath, repoId);
} catch (e) {
  if (e instanceof Error && e.message.includes('quarantine failed')) {
    // Stop all processes holding the WAL, then force rebuild
    logger.error('WAL quarantine failed — stop all GitNexus processes and run analyze --force');
  }
  throw e;
}

Prevention

Stop all GitNexus processes before running analyze to prevent WAL lock contention
On Windows, add antivirus exclusions for the .gitnexus/ directory
Ensure the storage directory is on a writable filesystem (not read-only mount)
Regularly run `gitnexus analyze` to keep the WAL checkpointed and small

When it happens

Trigger: Opening a read-only LadybugDB database via the pool adapter when the WAL is corrupt and the quarantine rename of <dbPath>.wal fails — typically because another process holds an exclusive lock on the .wal file, the filesystem is read-only, or permissions prevent the rename. The recovery chain: openLbug fails with WAL corruption → tryQuarantineAndReopen → fs.rename throws → this error.

Common situations: A `gitnexus serve` or MCP process holds the .wal file open while a concurrent process tries to open the same DB read-only; read-only mounted filesystem that prevents rename; a crashed process that left the .wal file with restrictive permissions; Windows file locking where Defender or another process briefly holds the file.

Related errors

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