{"record":{"id":"1cfcfae4ef4bdeec","repo":"abhigyanpatwari/GitNexus","slug":"gitnexus-could-not-move-the-ladybugdb-wal-sidecar-1cfcfa","errorCode":null,"errorMessage":"GitNexus could not move the LadybugDB WAL sidecar at ${dbPath}.wal because of a filesystem permission or file-lock error (${code}). The index does not need to be rebuilt — stop any GitNexus MCP or serve process using this repository, add an antivirus exclusion for the GitNexus storage directory, then re-run the failing command once the lock or permission is resolved.\n  Original error: ${msg}","messagePattern":"GitNexus could not move the LadybugDB WAL sidecar at (.+?)\\.wal because of a filesystem permission or file-lock error \\((.+?)\\)\\. The index does not need to be rebuilt — stop any GitNexus MCP or serve process using this repository, add an antivirus exclusion for the GitNexus storage directory, then re-run the failing command once the lock or permission is resolved\\.\n  Original error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/lbug/pool-adapter.ts","lineNumber":536,"sourceCode":"      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}\n\nasync function replayShadowPagesWithWritableOpen(dbPath: string): Promise<void> {\n  let db: lbug.Database | undefined;\n  try {","sourceCodeStart":518,"sourceCodeEnd":554,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/52924ef12c2290ceee4612526a828ec4cdf2047f/gitnexus/src/core/lbug/pool-adapter.ts#L518-L554","documentation":"renameFailureMessage's permission branch (gitnexus/src/core/lbug/sidecar-recovery.ts, thrown at pool-adapter.ts:531): the WAL-quarantine fs.rename failed with EACCES/EPERM/EBUSY — a filesystem permission or lock problem such as a competing process or antivirus scan. The index itself is sound; no rebuild is needed once the lock clears.","triggerScenarios":"Pool read-path recovery renaming <db>.wal while another GitNexus serve/MCP process or an antivirus scan holds the file; restrictive ACLs on the storage directory.","commonSituations":"Two MCP servers racing to open the same repo after a crash; Defender or another AV scanning the .wal at the moment of rename; storage on a lock-strict network share.","solutions":["Stop other GitNexus MCP/serve processes using this repository, then re-run the failing command","Add an antivirus exclusion for the GitNexus storage directory","Fix directory permissions so the serving user can rename files within it","Re-run once the lock or permission issue is resolved — the message explicitly says no rebuild is needed"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":"const isWalSidecarLockFailure = (e: unknown): boolean =>\n  e instanceof Error &&\n  e.message.includes('GitNexus could not move the LadybugDB WAL sidecar');","tryCatchPattern":"try {\n  await initLbug(repoId, dbPath);\n} catch (e) {\n  if (isWalSidecarLockFailure(e)) {\n    // index is fine — stop competing processes, then retry the same command\n    await stopCompetingGitNexusProcesses();\n    await initLbug(repoId, dbPath);\n  } else {\n    throw e;\n  }\n}","preventionTips":["Run one GitNexus opener per repository — serialize MCP/serve startups after a crash","Add antivirus exclusions for the storage directory so WAL files are not scanned mid-rename","Verify the serving user has rename permissions on the storage directory"],"tags":["gitnexus","ladybugdb","file-lock","eacces-eperm-ebusy","wal","antivirus"],"backgroundTag":"file-in-use-by-another-process","analyzedSha":"52924ef12c2290ceee4612526a828ec4cdf2047f","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}