abhigyanpatwari/GitNexus · error

GitNexus could not move the LadybugDB WAL sidecar at ${dbPat

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}

What it means

renameFailureMessage's permission branch (gitnexus/src/core/lbug/sidecar-recovery.ts, thrown at pool-adapter.ts:531): the WAL-quarantine fs.rename failed with EACCES/EPERM/EBUSY — a filesystem permission or lock problem such as a competing process or antivirus scan. The index itself is sound; no rebuild is needed once the lock clears.

Source

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

      logger: poolSidecarLogger,
      level: 'warn',
      reason: opts.reason,
    });
    return { kind: 'quarantined', path: quarantinePath };
  } catch (err) {
    if (isMissingFsError(err)) {
      const walStat = await statIfExists(`${dbPath}.wal`);
      if (walStat === null) {
        return { kind: 'peer-handled' };
      }
      // Defensive: ENOENT during rename but WAL still present afterwards.
      // Don't silently swallow — surface a classified error. ENOENT falls
      // through to shadowSidecarRecoveryMessage in renameFailureMessage.
      throw new Error(renameFailureMessage(dbPath, err));
    }
    // Classify the rename failure itself — EACCES/EPERM/EBUSY get the
    // permission-specific message; everything else falls through.
    throw new Error(renameFailureMessage(dbPath, err));
  }
}

async function probeDatabaseForShadowReplay(db: lbug.Database): Promise<void> {
  const conn = createConnection(db);
  try {
    const queryResult = await conn.query(SHADOW_REPLAY_PROBE_QUERY);
    const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
    await result.getAll();
    result.close?.();
  } finally {
    await conn.close().catch(() => {});
  }
}

async function replayShadowPagesWithWritableOpen(dbPath: string): Promise<void> {
  let db: lbug.Database | undefined;
  try {

View on GitHub (pinned to 52924ef12c)

Solutions

1. Stop other GitNexus MCP/serve processes using this repository, then re-run the failing command
2. Add an antivirus exclusion for the GitNexus storage directory
3. Fix directory permissions so the serving user can rename files within it
4. Re-run once the lock or permission issue is resolved — the message explicitly says no rebuild is needed

const isWalSidecarLockFailure = (e: unknown): boolean =>
  e instanceof Error &&
  e.message.includes('GitNexus could not move the LadybugDB WAL sidecar');

try {
  await initLbug(repoId, dbPath);
} catch (e) {
  if (isWalSidecarLockFailure(e)) {
    // index is fine — stop competing processes, then retry the same command
    await stopCompetingGitNexusProcesses();
    await initLbug(repoId, dbPath);
  } else {
    throw e;
  }
}

When it happens

Trigger: Pool read-path recovery renaming <db>.wal while another GitNexus serve/MCP process or an antivirus scan holds the file; restrictive ACLs on the storage directory.

Common situations: Two MCP servers racing to open the same repo after a crash; Defender or another AV scanning the .wal at the moment of rename; storage on a lock-strict network share.

Related errors

• Failed to remove the LadybugDB index files — still present a
• ${source}: branch name must not contain whitespace.
• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui
• LadybugDB WAL corruption detected for ${repoId}. Run `gitnex
• LadybugDB WAL corruption detected for ${repoId}. WAL corrupt

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