{"record":{"id":"8376fa00616c6e38","repo":"abhigyanpatwari/GitNexus","slug":"ladybugdb-checkpoint-sidecar-is-missing-for-dbpa","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}","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":"error","filePath":"gitnexus/src/core/lbug/lbug-adapter.ts","lineNumber":585,"sourceCode":"  await refuseLargeWalQuarantine(dbPath, 'read-only', err);\n  try {\n    await quarantineWalForMissingShadow(dbPath, {\n      logger,\n      level: 'warn',\n      reason: 'read-only recovery',\n    });\n  } catch (renameErr) {\n    throw new Error(renameFailureMessage(dbPath, renameErr));\n  }\n\n  const reopened = await openLbugConnection(lbug, dbPath, { readOnly: true });\n  try {\n    await queryAndDrain(reopened.conn, READ_ONLY_SHADOW_REPLAY_PROBE);\n    return reopened;\n  } catch (retryErr) {\n    await closeLbugConnection(reopened);\n    if (isMissingShadowSidecarError(retryErr) || isReadOnlyShadowReplayError(retryErr)) {\n      throw new Error(shadowSidecarRecoveryMessage(dbPath, retryErr));\n    }\n    throw retryErr;\n  }\n};\n\nconst reopenWritableAfterMissingShadow = async (\n  dbPath: string,\n  err: unknown,\n): Promise<LbugConnectionHandle> => {\n  await refuseLargeWalQuarantine(dbPath, 'writable', err);\n  try {\n    await quarantineWalForMissingShadow(dbPath, {\n      logger,\n      level: 'warn',\n      reason: 'writable recovery',\n    });\n  } catch (renameErr) {\n    throw new Error(renameFailureMessage(dbPath, renameErr));","sourceCodeStart":567,"sourceCodeEnd":603,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/lbug/lbug-adapter.ts#L567-L603","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rebuild the index: `gitnexus analyze --force <repo-path> --index-only`, then restart `gitnexus serve`.","Ensure no process deletes the `.shadow`/`.wal` sidecar files from the storage directory.","If the storage is on a sync/overlay filesystem, exclude the `.gitnexus/` directory from syncing."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":"function isMissingShadowRebuildError(err): boolean {\n  return /checkpoint sidecar is missing for/i.test(\n    err instanceof Error ? err.message : String(err),\n  );\n}","tryCatchPattern":"try {\n  await ensureReadOnlyConnection(dbPath);\n} catch (err) {\n  if (/checkpoint sidecar is missing for/i.test(err.message)) {\n    // Only recovery is a rebuild; the read-only path cannot replay shadow pages.\n    console.error(err.message, '— run: gitnexus analyze --force <repo> --index-only');\n    process.exit(7);\n  }\n  throw err;\n}","preventionTips":["Never delete .shadow/.wal sidecar files from the storage directory.","Exclude the .gitnexus directory from sync/backup tools that might prune files.","Run analyze to completion so checkpoint rotation produces a complete sidecar set."],"tags":["ladybugdb","sidecar","shadow","checkpoint","recovery","rebuild"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}