{"record":{"id":"96494fb6b6499d31","repo":"abhigyanpatwari/GitNexus","slug":"ladybugdb-checkpoint-sidecar-is-missing-for-dbpa-96494f","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":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/lbug/pool-adapter.ts","lineNumber":527,"sourceCode":"  // than being re-wrapped as a rename failure.\n  await guardWalQuarantine(dbPath, opts.reason, opts.err, poolSidecarLogger);\n  try {\n    const quarantinePath = await quarantineWalForMissingShadow(dbPath, {\n      logger: poolSidecarLogger,\n      level: 'warn',\n      reason: opts.reason,\n    });\n    return { kind: 'quarantined', path: quarantinePath };\n  } catch (err) {\n    if (isMissingFsError(err)) {\n      const walStat = await statIfExists(`${dbPath}.wal`);\n      if (walStat === null) {\n        return { kind: 'peer-handled' };\n      }\n      // Defensive: ENOENT during rename but WAL still present afterwards.\n      // Don't silently swallow — surface a classified error. ENOENT falls\n      // through to shadowSidecarRecoveryMessage in renameFailureMessage.\n      throw new Error(renameFailureMessage(dbPath, err));\n    }\n    // Classify the rename failure itself — EACCES/EPERM/EBUSY get the\n    // permission-specific message; everything else falls through.\n    throw new Error(renameFailureMessage(dbPath, err));\n  }\n}\n\nasync function probeDatabaseForShadowReplay(db: lbug.Database): Promise<void> {\n  const conn = createConnection(db);\n  try {\n    const queryResult = await conn.query(SHADOW_REPLAY_PROBE_QUERY);\n    const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;\n    await result.getAll();\n    result.close?.();\n  } finally {\n    await conn.close().catch(() => {});\n  }\n}","sourceCodeStart":509,"sourceCodeEnd":545,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/core/lbug/pool-adapter.ts#L509-L545","documentation":"Produced via shadowSidecarRecoveryMessage from tryQuarantineForMissingShadow (gitnexus/src/core/lbug/pool-adapter.ts:527): during pool read-path shadow recovery, quarantining the WAL with fs.rename failed with a non-permission error (ENOENT race with the WAL still present, EIO, etc.), so the sidecar state cannot be recovered in place. The index must be rebuilt with `gitnexus analyze --force --index-only` and serve restarted.","triggerScenarios":"Opening a pool (initLbug via MCP/serve) against a database left in an inconsistent checkpoint-sidecar state after a crash, where the WAL-quarantine rename fails for a non-permission reason.","commonSituations":"Power loss or SIGKILL during a checkpoint; NFS/network volumes with unreliable rename semantics; storage moved or partially restored between the crash and the reopen.","solutions":["Run `gitnexus analyze --force <repo-path> --index-only`, then restart `gitnexus serve` / reconnect MCP","Read the 'Original error' tail — it names the actual errno behind the rename failure","If it recurs on every open, check filesystem health and, failing that, wipe the repo's storage dir and re-analyze from scratch"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":"const isMissingShadowSidecar = (e: unknown): boolean =>\n  e instanceof Error && e.message.includes('LadybugDB checkpoint sidecar is missing');","tryCatchPattern":"try {\n  await initLbug(repoId, dbPath);\n} catch (e) {\n  if (isMissingShadowSidecar(e)) {\n    // index needs a rebuild — run analyze --force --index-only, restart serve, then retry init\n    throw new Error('index requires rebuild: gitnexus analyze --force <repo> --index-only');\n  }\n  throw e;\n}","preventionTips":["Shut down serve/MCP gracefully so checkpoints complete before process exit","Avoid SIGKILL during analyze writebacks — in-flight checkpoints are the main source of sidecar damage","Keep the index off NFS/network volumes where rename semantics are unreliable"],"tags":["gitnexus","ladybugdb","wal","shadow-sidecar","checkpoint","recovery"],"backgroundTag":"wal-sidecar-recovery-failed","analyzedSha":"aac7515d2a8c50a1f8f923c6fb77218b333560d6","analyzedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}