abhigyanpatwari/GitNexus · error

LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui

Error message

LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebuild the index with `gitnexus analyze --force <repo-path> --index-only` and restart `gitnexus serve`.
  Original error: ${msg}

What it means

Produced via shadowSidecarRecoveryMessage from tryQuarantineForMissingShadow (gitnexus/src/core/lbug/pool-adapter.ts:527): during pool read-path shadow recovery, quarantining the WAL with fs.rename failed with a non-permission error (ENOENT race with the WAL still present, EIO, etc.), so the sidecar state cannot be recovered in place. The index must be rebuilt with `gitnexus analyze --force --index-only` and serve restarted.

Source

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

  // than being re-wrapped as a rename failure.
  await guardWalQuarantine(dbPath, opts.reason, opts.err, poolSidecarLogger);
  try {
    const quarantinePath = await quarantineWalForMissingShadow(dbPath, {
      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(() => {});
  }
}

View on GitHub (pinned to aac7515d2a)

Solutions

1. Run `gitnexus analyze --force <repo-path> --index-only`, then restart `gitnexus serve` / reconnect MCP
2. Read the 'Original error' tail — it names the actual errno behind the rename failure
3. If it recurs on every open, check filesystem health and, failing that, wipe the repo's storage dir and re-analyze from scratch

const isMissingShadowSidecar = (e: unknown): boolean =>
  e instanceof Error && e.message.includes('LadybugDB checkpoint sidecar is missing');

try {
  await initLbug(repoId, dbPath);
} catch (e) {
  if (isMissingShadowSidecar(e)) {
    // index needs a rebuild — run analyze --force --index-only, restart serve, then retry init
    throw new Error('index requires rebuild: gitnexus analyze --force <repo> --index-only');
  }
  throw e;
}

When it happens

Trigger: Opening a pool (initLbug via MCP/serve) against a database left in an inconsistent checkpoint-sidecar state after a crash, where the WAL-quarantine rename fails for a non-permission reason.

Common situations: Power loss or SIGKILL during a checkpoint; NFS/network volumes with unreliable rename semantics; storage moved or partially restored between the crash and the reopen.

Related errors

• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui
• ${source} must be a string.
• GitNexus could not move the LadybugDB WAL sidecar at ${dbPat
• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui
• LadybugDB WAL corruption detected at ${dbPath}. WAL corrupti

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