{"record":{"id":"aa859f5d0e2e6d4d","repo":"abhigyanpatwari/GitNexus","slug":"gitnexus-failed-to-remove-orphan-sidecar-path-b","errorCode":null,"errorMessage":"GitNexus: failed to remove orphan sidecar ${path.basename(sidecar)} (${code ?? 'UNKNOWN'}) while main DB file is missing; LadybugDB open may still fail: ${summarizeError(err)}","messagePattern":"GitNexus: failed to remove orphan sidecar (.+?) \\((.+?)\\) while main DB file is missing; LadybugDB open may still fail: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"gitnexus/src/core/lbug/lbug-adapter.ts","lineNumber":886,"sourceCode":"      try {\n        await fs.access(dbPath);\n      } catch (err) {\n        if (isMissingFileError(err)) {\n          // `.shadow` is documented by LadybugDB checkpointing and `.wal.checkpoint`\n          // was observed in the #1618 crash loop that motivated this recovery path.\n          const orphanSidecars = [`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`];\n          for (const sidecar of orphanSidecars) {\n            try {\n              await fs.unlink(sidecar);\n              logger.warn(\n                `GitNexus: removed orphan sidecar ${path.basename(sidecar)} (no main DB file present)`,\n              );\n            } catch (err) {\n              if (isMissingFileError(err)) {\n                continue;\n              }\n              const code = extractErrnoCode(err);\n              logger.warn(\n                `GitNexus: failed to remove orphan sidecar ${path.basename(sidecar)} (${code ?? 'UNKNOWN'}) while main DB file is missing; LadybugDB open may still fail: ${summarizeError(err)}`,\n              );\n            }\n          }\n        } else {\n          const code = extractErrnoCode(err);\n          logger.warn(\n            `GitNexus: unable to verify main DB file before orphan sidecar cleanup (${code ?? 'UNKNOWN'}); skipping cleanup: ${summarizeError(err)}`,\n          );\n        }\n      }\n\n      // Ensure parent directory exists\n      const parentDir = path.dirname(dbPath);\n      await fs.mkdir(parentDir, { recursive: true });\n      await preflightLbugSidecars(dbPath, {\n        mode: 'write',\n        logger,","sourceCodeStart":868,"sourceCodeEnd":904,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/0d1aed942f0e8b5d3bac27519fff441aceea722d/gitnexus/src/core/lbug/lbug-adapter.ts#L868-L904","documentation":"The main DB file is missing (fs.access threw ENOENT), so preflight tries to remove orphaned sidecar files (`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`) that would otherwise block a fresh open. One of the unlinks failed with a non-ENOENT error; the warn explicitly says the LadybugDB open that follows may still fail because of the leftover sidecar.","triggerScenarios":"Someone deleted the main DB file (or a crashed run left only sidecars); then `fs.unlink(sidecar)` hits EPERM/EACCES, EBUSY, or EISDIR-style errors. Startup continues, but the subsequent engine open can error out on the stale sidecar pair.","commonSituations":"Manual cleanup that deleted the DB but not its sidecars; Windows file handles held by antivirus/indexers; NFS silly-rename semantics; sidecar directories created by mistake at the sidecar path.","solutions":["Manually delete both sidecars while gitnexus is not running: `rm -f <dbPath>.shadow <dbPath>.wal.checkpoint`, then retry.","Close any process holding the files open (lsof/fuser on Unix, Resource Monitor on Windows) and retry.","Fix ownership/permissions on the DB directory so the running user can unlink.","Retry once — EBUSY from a scan is often transient."],"exampleFix":"# before: 'failed to remove orphan sidecar ... LadybugDB open may still fail'\nrm -f .gitnexus/db.lbug .gitnexus/db.lbug.shadow .gitnexus/db.lbug.wal.checkpoint\nnpx gitnexus analyze   # after: clean open with fresh DB and sidecars","handlingStrategy":"validation","validationCode":"// Before open: when the main DB is gone, clear ALL sidecars yourself\nimport { unlink } from 'node:fs/promises';\nconst sidecars = [`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`, `${dbPath}.wal`];\nawait Promise.allSettled(sidecars.map((f) => unlink(f))); // preflight then opens cleanly","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Delete the whole .gitnexus DB directory rather than just the main DB file.","Check for open handles (lsof/fuser) before cleanup on shared machines.","Keep DB writes off network filesystems where unlink semantics are weak."],"tags":["ladybugdb","wal","sidecar","cleanup","ebusy"],"backgroundTag":"stale-wal-sidecar","analyzedSha":"0d1aed942f0e8b5d3bac27519fff441aceea722d","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}