{"record":{"id":"fdaaa7e26933d59e","repo":"abhigyanpatwari/GitNexus","slug":"ladybugdb-checkpoint-sidecar-is-present-but-unreachable-for","errorCode":null,"errorMessage":"LadybugDB checkpoint sidecar is present but unreachable for ${dbPath}. The .shadow file is on disk, so the open likely failed on path reachability or a file lock (antivirus, another process holding a handle, or a non-ASCII path) rather than a missing sidecar. Check filesystem access and locks; only run `gitnexus analyze --force <repo-path> --index-only` if the index is genuinely broken.\n  Original error: ${msg.slice(0, 200)}","messagePattern":"LadybugDB checkpoint sidecar is present but unreachable for (.+?)\\. The \\.shadow file is on disk, so the open likely failed on path reachability or a file lock \\(antivirus, another process holding a handle, or a non-ASCII path\\) rather than a missing sidecar\\. Check filesystem access and locks; only run `gitnexus analyze --force <repo-path> --index-only` if the index is genuinely broken\\.\n  Original error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/lbug/sidecar-recovery.ts","lineNumber":378,"sourceCode":" * the warning text (e.g. 'read-only', 'writable', 'pool read-only recovery').\n */\nexport const guardWalQuarantine = async (\n  dbPath: string,\n  mode: string,\n  triggeringErr: unknown,\n  logger: SidecarRecoveryLogger,\n  crashEvidence?: WalCrashEvidence,\n): Promise<void> => {\n  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    if (crashEvidence?.kind === 'fts-inplace-checkpointed') {\n      const { failed } = await quarantineSidecarsForDirtyRecovery(dbPath, (message) =>\n        logger.warn(message),\n      );\n      if (failed.length > 0) {\n        throw new Error(ftsCrashParkFailureMessage(failed[0]!));\n      }\n      return;\n    }\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));","sourceCodeStart":360,"sourceCodeEnd":396,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/core/lbug/sidecar-recovery.ts#L360-L396","documentation":"guardWalQuarantine refuses to quarantine the WAL during recovery when the .shadow checkpoint sidecar is present on disk but unreachable (state.kind === 'present-shadow-refuse'). Presence of the .shadow means the open failed on path reachability or a file lock (antivirus, another process holding a handle, non-ASCII path) rather than a missing sidecar, so quarantining would be wrong; the error includes the first 200 chars of the original error.","triggerScenarios":"Running a recovery mode through guardWalQuarantine against a dbPath whose WAL open failed while a .shadow sidecar exists; the sidecar is on disk but the database open failed due to OS-level locks, antivirus scanning, or an unreachable/non-ASCII path.","commonSituations":"Antivirus or backup software holding a handle on sidecar files; the repo moved to a path with non-ASCII characters; two processes contending for the database; network drive where the sidecar path is temporarily unreachable.","solutions":["Check filesystem access and locks: close other GitNexus MCP/serve processes and any antivirus/backup handles on the .gitnexus directory.","Verify the repo path is fully reachable (no network drive issues, avoid non-ASCII path segments if possible).","Only if the index is genuinely broken, run `gitnexus analyze --force <repo-path> --index-only` to rebuild."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import fs from 'node:fs';\nconst shadowExists = fs.existsSync(dbPath + '.shadow');\nif (shadowExists) {\n  console.warn('.shadow sidecar present; ensure no AV/backup locks and the path is reachable before recovery.');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runRecovery(dbPath);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('quarantine WAL')) {\n    console.error('Close AV/backup handles and other GitNexus processes, then retry; avoid non-ASCII paths.');\n  } else throw err;\n}","preventionTips":["Exclude .gitnexus directories from antivirus real-time scanning.","Keep repo paths ASCII and locally mounted (avoid flaky network drives for indexes).","Close all GitNexus MCP/serve processes before running recovery."],"tags":["database","wal","file-lock","sidecar","recovery"],"backgroundTag":"file-open-failed","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-09-15T23:29:44.066Z","contentChangedAt":"2026-09-15T23:29:44.066Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}