LadybugDB WAL corruption detected for

Error message

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

What it means

doInitLbug's WAL-corruption retry (gitnexus/src/core/lbug/pool-adapter.ts:769): the open failed as corruption, quarantine-and-reopen was attempted, and the retry open itself threw — the parenthesized text is that retry failure. The standing advice (WAL_RECOVERY_SUGGESTION) applies: force a full rebuild.

Solutions

Run `gitnexus analyze --force` on the repo to rebuild the whole index
Read the parenthesized retry error — sidecar or permission issues there may require stopping a competing process first
If corruption recurs across rebuilds, test the disk and storage volume for hardware faults

Defensive patterns

Strategy: retry

Type guard

const isWalCorruptionRecoveryFailed = (e: unknown): boolean =>
  e instanceof Error &&
  e.message.includes('WAL corruption detected') &&
  e.message.includes('analyze --force');

Try / catch

try {
  await initLbug(repoId, dbPath);
} catch (e) {
  if (isWalCorruptionRecoveryFailed(e)) {
    // quarantine AND reopen both failed — nothing left but a forced rebuild
    throw new Error('index unrecoverable in place: gitnexus analyze --force required');
  }
  throw e;
}

Prevention

Do not downgrade LadybugDB/GitNexus below the version that wrote an index
Keep sufficient disk so checkpoints and WAL replay never truncate
If this repeats on fresh rebuilds, suspect hardware and run disk diagnostics

When it happens

Trigger: initLbug on a repo whose WAL is corrupted AND the post-quarantine reopen still fails — damage beyond the WAL into the main DB file, or a sidecar state the replay rejects.

Common situations: Crash mid-checkpoint leaving both .wal and the main DB inconsistent; truncated files after a full disk; opening an index written by a newer LadybugDB version after a downgrade.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-09-15). Data as JSON: /api/errors/46f2453aa4095454. Report an issue: GitHub.

Appendix: source

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

      // Not retryable: the on-disk file's storage version doesn't change
      // on its own. Fail immediately with an actionable message.
      throwIfStorageVersionMismatch(lastError);
      if (lastError instanceof FtsReaderUnrepairableError) {
        throw lastError;
      }

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

      if (!shared) {
        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;
        }
        if (
          lastError.message.includes('Could not set lock') ||
          /\block(\b|ed|ing)/i.test(lastError.message)

View on GitHub (pinned to ac9a4e9abd)