{"record":{"id":"61be9e476148ad62","repo":"abhigyanpatwari/GitNexus","slug":"ladybugdb-checkpoint-sidecar-is-missing-for-dbpa-61be9e","errorCode":null,"errorMessage":"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.slice(0, 200)}","messagePattern":"LadybugDB checkpoint sidecar is missing for (.+?)\\. Rebuild the index with `gitnexus analyze --force <repo-path> --index-only` and restart `gitnexus serve`\\.\n  Original error: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"gitnexus/src/core/lbug/sidecar-recovery.ts","lineNumber":319,"sourceCode":"  const state = await inspectLbugSidecars(dbPath);\n  if (state.kind === 'wal-with-shadow') {\n    warnOnce(\n      logger,\n      `${dbPath}:present-shadow-refuse:${mode}`,\n      `GitNexus: refusing to quarantine WAL at ${dbPath}.wal during ${mode} recovery — ` +\n        'the .shadow sidecar is present on disk, so the open likely failed on path reachability or a lock ' +\n        'rather than a missing shadow. Run `gitnexus analyze --force <repo-path> --index-only` if the index is genuinely broken.',\n    );\n    throw new Error(presentShadowUnreachableMessage(dbPath, triggeringErr));\n  }\n  if (state.kind === 'orphan-wal') {\n    warnOnce(\n      logger,\n      `${dbPath}:large-wal-refuse:${mode}`,\n      `GitNexus: refusing to quarantine large WAL (${state.walBytes} bytes) at ${dbPath}.wal during ${mode} recovery; ` +\n        'manual recovery required — run `gitnexus analyze --force <repo-path> --index-only`.',\n    );\n    throw new Error(shadowSidecarRecoveryMessage(dbPath, triggeringErr));\n  }\n};\n\nexport async function quarantineWalForMissingShadow(\n  dbPath: string,\n  options: {\n    logger: SidecarRecoveryLogger;\n    level?: 'debug' | 'info' | 'warn';\n    reason?: string;\n  },\n): Promise<string> {\n  const walPath = `${dbPath}.wal`;\n  const quarantinePath = `${walPath}.missing-shadow.${Date.now()}-${Math.random()\n    .toString(36)\n    .slice(2)}`;\n  await fs.rename(walPath, quarantinePath);\n\n  const message =","sourceCodeStart":301,"sourceCodeEnd":337,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/lbug/sidecar-recovery.ts#L301-L337","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await enforceSidecarRecoveryPolicy(dbPath, mode, triggeringErr, logger);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('checkpoint sidecar is missing')) {\n    // Orphan WAL — manual recovery required, force rebuild\n    logger.error('Orphan WAL detected — run `gitnexus analyze --force` to rebuild');\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["ladybugdb","sidecar","orphan-wal","checkpoint","corruption","recovery"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}