{"record":{"id":"e6c535193652f916","repo":"abhigyanpatwari/GitNexus","slug":"gitnexus-could-not-move-the-ladybugdb-wal-sidecar","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":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/lbug/lbug-adapter.ts","lineNumber":575,"sourceCode":"  mode: 'read-only' | 'writable',\n  triggeringErr: unknown,\n): Promise<void> => {\n  await guardWalQuarantine(dbPath, mode, triggeringErr, logger);\n};\n\nconst reopenReadOnlyAfterMissingShadow = async (\n  dbPath: string,\n  err: unknown,\n): Promise<LbugConnectionHandle> => {\n  await refuseLargeWalQuarantine(dbPath, 'read-only', err);\n  try {\n    await quarantineWalForMissingShadow(dbPath, {\n      logger,\n      level: 'warn',\n      reason: 'read-only recovery',\n    });\n  } catch (renameErr) {\n    throw new Error(renameFailureMessage(dbPath, renameErr));\n  }\n\n  const reopened = await openLbugConnection(lbug, dbPath, { readOnly: true });\n  try {\n    await queryAndDrain(reopened.conn, READ_ONLY_SHADOW_REPLAY_PROBE);\n    return reopened;\n  } catch (retryErr) {\n    await closeLbugConnection(reopened);\n    if (isMissingShadowSidecarError(retryErr) || isReadOnlyShadowReplayError(retryErr)) {\n      throw new Error(shadowSidecarRecoveryMessage(dbPath, retryErr));\n    }\n    throw retryErr;\n  }\n};\n\nconst reopenWritableAfterMissingShadow = async (\n  dbPath: string,\n  err: unknown,","sourceCodeStart":557,"sourceCodeEnd":593,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/lbug/lbug-adapter.ts#L557-L593","documentation":"Thrown on the read-only recovery path (`reopenReadOnlyAfterMissingShadow`) when quarantining the WAL sidecar (renaming `.wal` aside to recover) fails with a filesystem permission or file-lock error. `renameFailureMessage` classifies the cause: EACCES/EPERM/EBUSY produce a permission/lock-specific message (no rebuild needed — the index is fine once the lock clears), while other codes fall through to the rebuild message. This is the read-only branch that runs when a serve/MCP path hits a missing checkpoint `.shadow`.","triggerScenarios":"`quarantineWalForMissingShadow` calls `fs.rename` on the `.wal` file and the OS rejects it with EACCES/EPERM/EBUSY during a read-only reopen attempt. Typically an antivirus scan or another gitnexus process holds an open handle on the WAL.","commonSituations":"Windows antivirus locking the `.wal` during a scan; a lingering `gitnexus serve`/MCP process holding the index; a read-only container mount that also denies the rename; ACLs on the storage directory.","solutions":["Stop any GitNexus MCP or serve process using this repository, then re-run the failing command.","Add an antivirus exclusion for the GitNexus storage directory (`.gitnexus/`).","Fix filesystem permissions/ACLs on the storage directory so the rename can succeed.","The index does NOT need to be rebuilt for the permission/lock class — re-run after the lock clears."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isWalRenameLockError(err): boolean {\n  return /could not move the LadybugDB WAL sidecar.*permission or file-lock/i.test(\n    err instanceof Error ? err.message : String(err),\n  );\n}","tryCatchPattern":"try {\n  await openReadOnly(dbPath);\n} catch (err) {\n  if (/WAL sidecar.*permission or file-lock/i.test(err.message)) {\n    // Stop other gitnexus processes / add AV exclusion, then re-run.\n    // No rebuild needed for this class.\n    console.error(err.message);\n    process.exit(6);\n  }\n  throw err;\n}","preventionTips":["Stop all gitnexus serve/MCP processes before running analyze on the same repo.","Add an antivirus exclusion for the .gitnexus storage directory.","Ensure the runtime user has write+rename permission on the storage directory."],"tags":["ladybugdb","wal","file-lock","permission","sidecar","recovery"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}