What causes "LadybugDB checkpoint sidecar is missing for ${dbPath}. Rebuild the index with `gitnexus analyze --force --index-only` and restart `gitnexus serve`. Original error: ${msg.slice(0, 200)}" in abhigyanpatwari/GitNexus?

Run `gitnexus analyze --force --index-only` to rebuild the index from scratch — this is the required recovery action

abhigyanpatwari/GitNexus · critical · 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.slice(0, 200)}

What it means

Thrown by enforceSidecarRecoveryPolicy when the sidecar inspection finds an orphan WAL (state.kind === 'orphan-wal') — a large .wal file exists without a corresponding .shadow checkpoint sidecar. This means the checkpoint data that should accompany the WAL is missing, likely due to a crashed checkpoint or a partial wipe. Unlike the missing-shadow case where quarantine may be safe, an orphan WAL is too risky to auto-quarantine (it may contain committed transactions). The error requires manual recovery via `gitnexus analyze --force`. The original triggering error is truncated to 200 chars.

Source

Thrown at gitnexus/src/core/lbug/sidecar-recovery.ts:319

  const state = await inspectLbugSidecars(dbPath);
  if (state.kind === 'wal-with-shadow') {
    warnOnce(
      logger,
      `${dbPath}:present-shadow-refuse:${mode}`,
      `GitNexus: refusing to quarantine WAL at ${dbPath}.wal during ${mode} recovery — ` +
        'the .shadow sidecar is present on disk, so the open likely failed on path reachability or a lock ' +
        'rather than a missing shadow. Run `gitnexus analyze --force <repo-path> --index-only` if the index is genuinely broken.',
    );
    throw new Error(presentShadowUnreachableMessage(dbPath, triggeringErr));
  }
  if (state.kind === 'orphan-wal') {
    warnOnce(
      logger,
      `${dbPath}:large-wal-refuse:${mode}`,
      `GitNexus: refusing to quarantine large WAL (${state.walBytes} bytes) at ${dbPath}.wal during ${mode} recovery; ` +
        'manual recovery required — run `gitnexus analyze --force <repo-path> --index-only`.',
    );
    throw new Error(shadowSidecarRecoveryMessage(dbPath, triggeringErr));
  }
};

export async function quarantineWalForMissingShadow(
  dbPath: string,
  options: {
    logger: SidecarRecoveryLogger;
    level?: 'debug' | 'info' | 'warn';
    reason?: string;
  },
): Promise<string> {
  const walPath = `${dbPath}.wal`;
  const quarantinePath = `${walPath}.missing-shadow.${Date.now()}-${Math.random()
    .toString(36)
    .slice(2)}`;
  await fs.rename(walPath, quarantinePath);

  const message =

View on GitHub (pinned to d540b00184)

Solutions

Run `gitnexus analyze --force <repo-path> --index-only` to rebuild the index from scratch — this is the required recovery action
Restart `gitnexus serve` after the rebuild completes
If `--force` fails, manually delete the .gitnexus/ storage directory and re-run `gitnexus analyze`
Check disk space before rebuilding — the orphan WAL suggests a prior disk-full event may have caused the checkpoint failure

Defensive patterns

Strategy: fallback

Try / catch

try {
  await enforceSidecarRecoveryPolicy(dbPath, mode, triggeringErr, logger);
} catch (e) {
  if (e instanceof Error && e.message.includes('checkpoint sidecar is missing')) {
    // Orphan WAL — manual recovery required, force rebuild
    logger.error('Orphan WAL detected — run `gitnexus analyze --force` to rebuild');
  }
  throw e;
}

Prevention

Run `gitnexus analyze` regularly to keep WALs checkpointed and small — large orphan WALs indicate interrupted checkpoints
Monitor disk space — running out of space during checkpoint is a primary cause of orphan WALs
Avoid force-killing the GitNexus process during analyze — use graceful shutdown to allow checkpoint completion
After a power failure or crash, run `gitnexus analyze --force` proactively to clean up orphaned WAL state

When it happens

Trigger: During DB open recovery, inspectLbugSidecars finds the .wal file is large (above the orphan threshold) and the .shadow sidecar is absent. This happens after a checkpoint crashed mid-rotation (the old .shadow was removed but the new one wasn't created), a partial file wipe that deleted .shadow but left .wal, or a filesystem error during checkpoint that left the WAL orphaned.

Common situations: A power failure or force-kill during LadybugDB's checkpoint rotation; a partial manual deletion of .gitnexus/ files; a filesystem corruption that removed the .shadow file; running out of disk space during checkpoint so the .shadow couldn't be written; a crashed analyze that left the WAL in an orphaned state.

Related errors

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