abhigyanpatwari/GitNexus · error · 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`.\n  Original error: ${msg}

What it means

Thrown on the read-only recovery path when, after quarantining the WAL and reopening the DB read-only, the shadow-replay probe (`READ_ONLY_SHADOW_REPLAY_PROBE`) fails with a missing-shadow or read-only-shadow-replay error. `shadowSidecarRecoveryMessage` produces the canonical guidance: the checkpoint `.shadow` sidecar is genuinely missing/unusable and a read-only connection cannot replay shadow pages, so the only recovery is a forced rebuild of the index.

Source

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

  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 reopenWritableAfterMissingShadow = async (
  dbPath: string,
  err: unknown,
): Promise<LbugConnectionHandle> => {
  await refuseLargeWalQuarantine(dbPath, 'writable', err);
  try {
    await quarantineWalForMissingShadow(dbPath, {
      logger,
      level: 'warn',
      reason: 'writable recovery',
    });
  } catch (renameErr) {
    throw new Error(renameFailureMessage(dbPath, renameErr));

View on GitHub (pinned to d540b00184)

Solutions

1. Rebuild the index: `gitnexus analyze --force <repo-path> --index-only`, then restart `gitnexus serve`.
2. Ensure no process deletes the `.shadow`/`.wal` sidecar files from the storage directory.
3. If the storage is on a sync/overlay filesystem, exclude the `.gitnexus/` directory from syncing.

function isMissingShadowRebuildError(err): boolean {
  return /checkpoint sidecar is missing for/i.test(
    err instanceof Error ? err.message : String(err),
  );
}

try {
  await ensureReadOnlyConnection(dbPath);
} catch (err) {
  if (/checkpoint sidecar is missing for/i.test(err.message)) {
    // Only recovery is a rebuild; the read-only path cannot replay shadow pages.
    console.error(err.message, '— run: gitnexus analyze --force <repo> --index-only');
    process.exit(7);
  }
  throw err;
}

When it happens

Trigger: The LadybugDB checkpoint `.shadow` sidecar is missing or unusable AND the connection is read-only (a serve/MCP path). The WAL was quarantined but the read-only reopen still cannot replay shadow pages, so the probe fails.

Common situations: The `.shadow` file was deleted (manual cleanup, partial sync, AV quarantine) while a serve/MCP process tries to open the index read-only; a crashed previous run left the sidecar set incomplete.

Related errors

• LadybugDB checkpoint sidecar is present but unreachable for
• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui
• LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebui
• GitNexus could not move the LadybugDB WAL sidecar at ${dbPat
• LadybugDB WAL corruption detected at ${dbPath}. WAL corrupti

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