{"record":{"id":"123f56df6064d76e","repo":"abhigyanpatwari/GitNexus","slug":"ladybugdb-wal-corruption-detected-at-dbpath-wa","errorCode":null,"errorMessage":"LadybugDB WAL corruption detected at ${dbPath}. WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.\\n  Original error: ${msg}","messagePattern":"LadybugDB WAL corruption detected at (.+?)\\. WAL corruption detected\\. Run `gitnexus analyze --force` to rebuild the index\\.\\\\n  Original error: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"gitnexus/src/core/lbug/lbug-adapter.ts","lineNumber":711,"sourceCode":"      //   - \"already exists\": expected idempotent re-create on existing DBs\n      //   - \"could not set lock on file\": LadybugDB v0.18.0 emits this on\n      //     Windows when CREATE NODE TABLE runs against a path that was\n      //     just opened (the WAL handle from a fresh Database briefly\n      //     contests the table's first-write lock). The table is created\n      //     anyway and any genuine cross-process lock contention surfaces\n      //     on the next operation via withLbugDb's retry. Logging it here\n      //     would just be noise in CI.\n      //\n      // WAL corruption: the first DDL write after DB open triggers WAL\n      // replay — if the WAL file was left in a corrupt state by an\n      // interrupted previous run, the native engine throws here. Rather\n      // than logging a WARN and continuing in a broken state, close the\n      // DB cleanly and surface an actionable error so the caller (serve,\n      // MCP, analyze) can exit with a clear recovery message.\n      if (isWalCorruptionError(err)) {\n        await safeClose();\n        resetOpenConnectionState();\n        throw new Error(\n          `LadybugDB WAL corruption detected at ${dbPath}. ${WAL_RECOVERY_SUGGESTION}\\n` +\n            `  Original error: ${msg.slice(0, 200)}`,\n        );\n      }\n      if (!msg.includes('already exists') && !isDbBusyError(err) && !isReadOnlyDbError(err)) {\n        logger.warn(`⚠️ Schema creation warning: ${msg.slice(0, 120)}`);\n      }\n    }\n  }\n\n  return null;\n};\n\nexport const initLbug = async (dbPath: string) => {\n  return runWithSessionLock(() => ensureLbugInitialized(dbPath));\n};\n\n/**","sourceCodeStart":693,"sourceCodeEnd":729,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/lbug/lbug-adapter.ts#L693-L729","documentation":"Thrown by the schema-creation loop when `isWalCorruptionError` matches the native engine's error (regex: `corrupt(ed)? wal`, `invalid wal record`, `wal.*corrupt`, `checksum.*wal`). The first DDL write after DB open triggers WAL replay; if a previous run was interrupted and left the WAL in a corrupt state, the native engine throws here. Instead of logging a warning and continuing broken, the DB is closed cleanly, connection state reset, and an actionable error with `WAL_RECOVERY_SUGGESTION` is surfaced so the caller (serve/MCP/analyze) exits with a clear recovery message.","triggerScenarios":"Opening a database whose `.wal` was left corrupt by an interrupted previous run (crash, kill -9, power loss mid-write). The corruption is detected on the first DDL/schema write because that forces WAL replay, and `isWalCorruptionError` matches the engine message.","commonSituations":"A machine crash or OOM-kill during `gitnexus analyze` corrupts the WAL; a disk filled mid-checkpoint; an abrupt container termination while the engine was flushing the WAL.","solutions":["Rebuild the index: `gitnexus analyze --force` (the WAL cannot be repaired incrementally — a clean rebuild is the only remedy).","Ensure analyze runs to completion (do not kill -9 the process mid-write) to avoid leaving the WAL corrupt again.","Free disk space first if the original corruption was caused by a full disk during checkpoint."],"exampleFix":"// recovery\ngitnexus analyze --force <repo-path> --index-only","handlingStrategy":"fallback","validationCode":null,"typeGuard":"import { isWalCorruptionError } from 'gitnexus/dist/core/lbug/lbug-config.js';\n\n// Reuse the shipped classifier on a caught error\nfunction isWalCorruption(err): boolean {\n  return isWalCorruptionError(err) || /WAL corruption detected at/i.test(\n    err instanceof Error ? err.message : String(err),\n  );\n}","tryCatchPattern":"try {\n  await initLbug(dbPath);\n} catch (err) {\n  if (/WAL corruption detected at/i.test(err.message)) {\n    // Only remedy is a clean rebuild — the WAL cannot be repaired incrementally.\n    console.error(err.message);\n    await runRebuild(repoPath); // gitnexus analyze --force <repo> --index-only\n    return;\n  }\n  throw err;\n}","preventionTips":["Let analyze run to completion — do not kill -9 mid-write.","Keep disk space free so checkpoints never fail mid-flush.","After a crash or OOM-kill, proactively rebuild before serving to avoid hitting corruption at query time."],"tags":["ladybugdb","wal","corruption","data-integrity","rebuild","schema"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}