abhigyanpatwari/GitNexus · error

LadybugDB not found at ${dbPath}. Run: gitnexus analyze

Error message

LadybugDB not found at ${dbPath}. Run: gitnexus analyze

What it means

Thrown by doInitLbug when fs.stat(dbPath) fails — the LadybugDB database file does not exist at the expected storage path. The pool adapter's initialization path checks for the DB file before attempting to open it; if the file isn't there, the repo was never analyzed (or the storage directory was deleted/corrupted). The dbPath is constructed from the repo's storage paths (typically .gitnexus/<repo-hash>/graph.db under the repo root or a configured storage root).

Source

Thrown at gitnexus/src/core/lbug/pool-adapter.ts:718

  try {
    await promise;
  } finally {
    initPromises.delete(repoId);
  }
  return true;
};

/**
 * Internal init — creates DB, pre-warms connections, loads FTS, then registers pool.
 * Pool entry is registered LAST so concurrent executeQuery calls see either
 * "not initialized" (and throw) or a fully ready pool — never a half-built one.
 */
async function doInitLbug(repoId: string, dbPath: string): Promise<void> {
  // Check if database exists
  try {
    await fs.stat(dbPath);
  } catch {
    throw new Error(`LadybugDB not found at ${dbPath}. Run: gitnexus analyze`);
  }

  evictLRU();

  // Reuse an existing native Database if another repoId already opened this path.
  // This prevents buffer manager exhaustion from multiple mmap regions on the same file.
  let shared = dbCache.get(dbPath);
  if (shared && !shared.external && shared.dbIdentity) {
    // #2614 F2: a cached read-only Database is keyed by dbPath and shared across
    // pool consumers. If the on-disk index was rebuilt/swapped (new inode) while
    // ANOTHER consumer still holds this handle (refCount kept it alive), reusing
    // it serves a superseded index. Unreachable via the MCP backend (one
    // consumer per lbugPath ⇒ refCount hits 0 ⇒ closeOne reopens fresh); a
    // complete fix needs per-inode handles rather than a dbPath-keyed cache.
    // Surface it so the corner is observable instead of silently stale.
    const current = await statDbIdentity(dbPath);
    if (dbIdentityChanged(shared.dbIdentity, current)) {
      realStderrWrite(

View on GitHub (pinned to d540b00184)

Solutions

1. Run `gitnexus analyze` to create the initial index — this builds the LadybugDB database at the expected path
2. Verify the storage path is correct: check that .gitnexus/ exists under the repo root after analyze completes
3. If the DB was at a different path (version migration), run `gitnexus analyze --force` to rebuild at the current version's expected path
4. Check that the GitNexus process has write permissions to the storage directory

// Verify the DB file exists before initializing the pool
import { stat } from 'fs/promises';
async function dbExists(dbPath: string): Promise<boolean> {
  try {
    const s = await stat(dbPath);
    return s.isFile();
  } catch {
    return false;
  }
}
// Before calling initLbug:
if (!(await dbExists(dbPath))) {
  throw new Error('Index not found — run `gitnexus analyze` first');
}

try {
  await doInitLbug(repoId, dbPath);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('LadybugDB not found')) {
    logger.error('Index missing — run `gitnexus analyze` to create it');
  }
  throw e;
}

When it happens

Trigger: Calling initLbug (or any pool-backed query) for a repoId whose analyze has never been run; calling it after the .gitnexus/ storage directory was manually deleted; a misconfigured storage root pointing to a path where the DB doesn't exist; the repoId hashing changed between versions so the old DB is at a different path.

Common situations: Fresh clone of a repo where the user tries to run `gitnexus serve` or MCP tools before running `gitnexus analyze`; a CI pipeline that cleans the workspace between runs; a corrupted or partially-deleted .gitnexus/ directory after a failed wipe; a storage path configuration change.

Related errors

• LadybugDB not initialized for repo "${repoId}". Call initLbu
• Failed to remove the LadybugDB index files — still present a
• LadybugDB WAL corruption detected for ${repoId}. Run `gitnex
• LadybugDB WAL corruption detected for ${repoId}. WAL corrupt
• LadybugDB unavailable for ${repoId}. Another process may be

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/6aebe54eb4e21743. Report an issue: GitHub.