abhigyanpatwari/GitNexus · critical · Error

LadybugDB WAL corruption detected at ${dbPath}. WAL corrupti

Error message

LadybugDB WAL corruption detected at ${dbPath}. WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.\n  Original error: ${msg}

What it means

Thrown by the schema-creation loop when `isWalCorruptionError` matches the native engine's error (regex: `corrupt(ed)? wal`, `invalid wal record`, `wal.*corrupt`, `checksum.*wal`). The first DDL write after DB open triggers WAL replay; if a previous run was interrupted and left the WAL in a corrupt state, the native engine throws here. Instead of logging a warning and continuing broken, the DB is closed cleanly, connection state reset, and an actionable error with `WAL_RECOVERY_SUGGESTION` is surfaced so the caller (serve/MCP/analyze) exits with a clear recovery message.

Source

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

      //   - "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 (!msg.includes('already exists') && !isDbBusyError(err) && !isReadOnlyDbError(err)) {
        logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);
      }
    }
  }

  return null;
};

export const initLbug = async (dbPath: string) => {
  return runWithSessionLock(() => ensureLbugInitialized(dbPath));
};

/**

View on GitHub (pinned to d540b00184)

Solutions

1. Rebuild the index: `gitnexus analyze --force` (the WAL cannot be repaired incrementally — a clean rebuild is the only remedy).
2. Ensure analyze runs to completion (do not kill -9 the process mid-write) to avoid leaving the WAL corrupt again.
3. Free disk space first if the original corruption was caused by a full disk during checkpoint.

Example fix

// recovery
gitnexus analyze --force <repo-path> --index-only

import { isWalCorruptionError } from 'gitnexus/dist/core/lbug/lbug-config.js';

// Reuse the shipped classifier on a caught error
function isWalCorruption(err): boolean {
  return isWalCorruptionError(err) || /WAL corruption detected at/i.test(
    err instanceof Error ? err.message : String(err),
  );
}

try {
  await initLbug(dbPath);
} catch (err) {
  if (/WAL corruption detected at/i.test(err.message)) {
    // Only remedy is a clean rebuild — the WAL cannot be repaired incrementally.
    console.error(err.message);
    await runRebuild(repoPath); // gitnexus analyze --force <repo> --index-only
    return;
  }
  throw err;
}

When it happens

Trigger: Opening a database whose `.wal` was left corrupt by an interrupted previous run (crash, kill -9, power loss mid-write). The corruption is detected on the first DDL/schema write because that forces WAL replay, and `isWalCorruptionError` matches the engine message.

Common situations: A machine crash or OOM-kill during `gitnexus analyze` corrupts the WAL; a disk filled mid-checkpoint; an abrupt container termination while the engine was flushing the WAL.

Related errors

• [embed] Failed to delete stale embedding rows — aborting to
• GitNexus could not move the LadybugDB WAL sidecar at ${dbPat
• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui
• COPY failed for ${table}: ${retryMsg}${remedy}
• Prepare failed: ${errMsg}

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