GitNexus could not move the LadybugDB WAL sidecar at

Error message

GitNexus could not move the LadybugDB WAL sidecar at ${dbPath}.wal because of a filesystem permission or file-lock error (${code}). The index does not need to be rebuilt — stop any GitNexus MCP or serve process using this repository, add an antivirus exclusion for the GitNexus storage directory, then re-run the failing command once the lock or permission is resolved.
  Original error: ${msg.slice(0, 200)}

What it means

renameFailureMessage from lbug-adapter.ts (read-only recovery path, line 575): while recovering from a missing checkpoint sidecar, GitNexus tries to quarantine the WAL sidecar (${dbPath}.wal) by renaming it; the rename fails with a filesystem permission or file-lock errno (code). The message is explicit that the index does NOT need rebuilding — an external holder (another process, antivirus) is blocking the rename.

Solutions

Stop any GitNexus MCP or serve process using this repository, then re-run the failing command
Add an antivirus exclusion for the GitNexus storage directory (e.g. ~/.gitnexus)
Verify write permission on the storage directory and that it is not on a read-only filesystem
Re-run the command once the lock/permission is resolved — no rebuild is needed

Example fix

# before
# (serve running, AV scanning ~/.gitnexus)
$ gitnexus serve & gitnexus query ...
# after
$ gitnexus mcp stop
# Add AV exclusion for ~/.gitnexus, then:
gitnexus query ...

Defensive patterns

Strategy: retry

Validate before calling

import fs from 'node:fs';

fs.accessSync(path.dirname(dbPath), fs.constants.W_OK); // throws early if storage is not writable
fs.accessSync(`${dbPath}.wal`, fs.constants.W_OK);       // surfaces permission problems before recovery renames

Try / catch

try {
  await openAndQuery(dbPath);
} catch (err) {
  if (err instanceof Error && err.message.includes('could not move the LadybugDB WAL sidecar')) {
    // stop serve/MCP processes, add an AV exclusion, then re-run once — the index itself is intact, no rebuild
  }
  throw err;
}

Prevention

Add the GitNexus storage directory (e.g. ~/.gitnexus) to antivirus real-time-scan exclusions on Windows
Stop serve/MCP processes before running maintenance or recovery-triggering commands against the same index
Keep the storage directory on a local writable filesystem, not a locked network share

When it happens

Trigger: Antivirus/real-time scanning holding the .wal file open (typical on Windows); a concurrently running `gitnexus serve` or MCP process with an open handle on the database; storage directory on a read-only mount or with restrictive permissions; network filesystems that refuse locked renames.

Common situations: Windows workstations with Defender real-time protection scanning ~/.gitnexus; an MCP server left running in the IDE while maintenance commands execute; indexes stored on SMB/NFS shares.

Related errors

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

Appendix: source

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

): Promise<void> => {
  // Latitude defaults to refusal. Only the analyze writer passes
  // `fts-inplace-checkpointed`; serve never does (R9).
  await guardWalQuarantine(dbPath, mode, triggeringErr, logger, crashEvidence);
};

const reopenReadOnlyAfterMissingShadow = async (
  dbPath: string,
  err: unknown,
): Promise<LbugConnectionHandle> => {
  await refuseLargeWalQuarantine(dbPath, 'read-only', err);
  try {
    await quarantineWalForMissingShadow(dbPath, {
      logger,
      level: 'warn',
      reason: 'read-only recovery',
    });
  } catch (renameErr) {
    throw new Error(renameFailureMessage(dbPath, renameErr));
  }

  const reopened = await openLbugConnection(lbug, dbPath, { readOnly: true });
  try {
    await queryAndDrain(reopened.conn, READ_ONLY_SHADOW_REPLAY_PROBE);
    return reopened;
  } catch (retryErr) {
    await closeLbugConnection(reopened);
    if (isMissingShadowSidecarError(retryErr) || isReadOnlyShadowReplayError(retryErr)) {
      throw new Error(shadowSidecarRecoveryMessage(dbPath, retryErr));
    }
    throw retryErr;
  }
};

const writableFtsCrashWalEvidence = async (
  dbPath: string,
): Promise<WalCrashEvidence | undefined> => {

View on GitHub (pinned to ac9a4e9abd)