abhigyanpatwari/GitNexus · error

LadybugDB checkpoint sidecar is missing for

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.slice(0, 200)}

What it means

shadowSidecarRecoveryMessage from lbug-adapter.ts (read-only path, line 585): when a database is opened read-only, a probe query replays against the shadow/checkpoint sidecar; if the sidecar is missing, GitNexus quarantines the WAL, reopens read-only, and retries the probe. When the retry still fails with a missing-shadow or shadow-replay error, recovery is impossible without rebuilding and the error directs the operator to re-run analyze with --force --index-only.

Solutions

1. Run `gitnexus analyze --force <repo-path> --index-only` to rebuild the index from the repo, then restart `gitnexus serve`
2. If the error recurs, remove the stale database files under the storage dir entirely and run a full `gitnexus analyze --force <repo-path>`
3. When copying or backing up indexes, always copy the whole storage dir including all sidecar files, never just the main db file

Example fix

# before
$ gitnexus serve   # fails: checkpoint sidecar missing
# after
$ gitnexus analyze --force /path/to/repo --index-only
gitnexus serve

try {
  await startServe(repoPath);
} catch (err) {
  if (err instanceof Error && err.message.includes('checkpoint sidecar is missing')) {
    // recovery path: exec `gitnexus analyze --force <repo> --index-only`, then restart serve on success
    await rebuildIndex(repoPath);
    return startServe(repoPath);
  }
  throw err;
}

When it happens

Trigger: A previous run was interrupted between WAL checkpoint steps (kill, power loss, disk-full) leaving the checkpoint sidecar absent; someone copied or restored only the main database file without its sidecars; then serve/MCP/query tries to open the index read-only.

Common situations: CI runners killed mid-analyze; disk-full during checkpoint; partial backups or rsync of the storage dir that skipped sidecar files; storage cleanup scripts deleting 'unknown' files.

Related errors

• LadybugDB checkpoint sidecar is missing for
• GitNexus could not move the LadybugDB WAL sidecar at
• GitNexus: manual WAL checkpoint failed after retries
• LadybugDB checkpoint sidecar is missing for
• LadybugDB WAL corruption detected at

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

Appendix: source

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

  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> => {
  try {
    const meta = await loadMeta(path.dirname(dbPath));
    if (
      meta &&
      (allowsFtsCrashWalPark(meta.incrementalInProgress) ||
        hasRecoveredInPlaceFtsAbort(meta.capabilities?.fts))
    ) {
      return { kind: 'fts-inplace-checkpointed' };
    }
  } catch {

View on GitHub (pinned to ac9a4e9abd)