{"record":{"id":"cd40e548807f2779","repo":"abhigyanpatwari/GitNexus","slug":"ladybugdb-checkpoint-sidecar-is-missing-for-dbpa-cd40e5","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}\\n  The workspace appears to be read-only — mount it read-write to perform shadow replay recovery, or re-run `gitnexus analyze` on a writable filesystem to rebuild the index.","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: (.+?)\\\\n  The workspace appears to be read-only — mount it read-write to perform shadow replay recovery, or re-run `gitnexus analyze` on a writable filesystem to rebuild the index\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/lbug/lbug-adapter.ts","lineNumber":637,"sourceCode":"      await closeLbugConnection(handle);\n      return await reopenReadOnlyAfterMissingShadow(dbPath, err);\n    }\n    if (!isReadOnlyShadowReplayError(err)) {\n      await closeLbugConnection(handle);\n      throw err;\n    }\n    shadowReplayErr = err;\n  }\n\n  await closeLbugConnection(handle);\n\n  let writable: LbugConnectionHandle;\n  try {\n    writable = await openLbugConnection(lbug, dbPath);\n  } catch (openErr) {\n    const code = extractErrnoCode(openErr);\n    if (code === 'EROFS' || code === 'EACCES' || code === 'EPERM') {\n      throw new Error(\n        shadowSidecarRecoveryMessage(dbPath, shadowReplayErr) +\n          '\\n  The workspace appears to be read-only — mount it read-write to perform shadow replay recovery,' +\n          ' or re-run `gitnexus analyze` on a writable filesystem to rebuild the index.',\n      );\n    }\n    throw openErr;\n  }\n  let missingShadowError: unknown;\n  try {\n    await queryAndDrain(writable.conn, READ_ONLY_SHADOW_REPLAY_PROBE);\n  } catch (err) {\n    if (isMissingShadowSidecarError(err)) {\n      missingShadowError = err;\n    } else {\n      throw err;\n    }\n  } finally {\n    await closeLbugConnection(writable);","sourceCodeStart":619,"sourceCodeEnd":655,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/lbug/lbug-adapter.ts#L619-L655","documentation":"Thrown by `ensureReadOnlyConnectionUsable` when the read-only shadow-replay probe fails and the writable reopen needed to replay shadow pages is blocked by a read-only workspace (openLbugConnection throws EROFS/EACCES/EPERM). It appends a read-only-specific tail to `shadowSidecarRecoveryMessage`: the missing shadow cannot be recovered in-place because the filesystem refuses writes. Two distinct remedies are valid depending on whether you can remount or must rebuild elsewhere.","triggerScenarios":"The checkpoint `.shadow` sidecar is missing AND the workspace/storage directory is mounted read-only (EROFS) or denies writes (EACCES/EPERM), so the writable recovery open that would replay shadow pages fails at the OS level.","commonSituations":"Running `gitnexus serve` against a read-only mounted index directory (a common deployment for shared, immutable indexes); a container with a read-only volume mount for the storage dir; permission ACLs denying the serve user write access.","solutions":["Remount the workspace read-write (or grant the serve user write permission) so shadow-replay recovery can run.","Re-run `gitnexus analyze` on a writable filesystem to rebuild a complete index, then serve the rebuilt index.","If read-only serving is intentional and permanent, always rebuild on a writable FS and copy the complete sidecar set over."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":"function isReadOnlyWorkspaceShadowError(err): boolean {\n  return /workspace appears to be read-only/i.test(\n    err instanceof Error ? err.message : String(err),\n  );\n}","tryCatchPattern":"try {\n  await ensureReadOnlyConnection(dbPath);\n} catch (err) {\n  if (/workspace appears to be read-only/i.test(err.message)) {\n    // Either remount read-write to replay the shadow, or rebuild on a writable FS.\n    console.error(err.message);\n    process.exit(8);\n  }\n  throw err;\n}","preventionTips":["Build indexes on a writable filesystem even if you serve them read-only.","If serving read-only permanently, copy a COMPLETE sidecar set; never a partial one.","Mount the storage directory read-write for maintenance/recovery windows."],"tags":["ladybugdb","sidecar","shadow","read-only","filesystem","recovery"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}