{"record":{"id":"09f6dbed8a5c6134","repo":"abhigyanpatwari/GitNexus","slug":"the-ladybugdb-graph-store-at-lbugpath-is-not-a-usable","errorCode":null,"errorMessage":"The LadybugDB graph store at ${lbugPath} is not a usable database file. Run gitnexus analyze first.","messagePattern":"The LadybugDB graph store at (.+?) is not a usable database file\\. Run gitnexus analyze first\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/cli/embeddings-sync.ts","lineNumber":70,"sourceCode":"      `Cannot acquire the index lock at ${metaDir}; refusing an unlocked embeddings sync.`,\n    );\n    const meta = await loadMeta(metaDir);\n    if (!meta)\n      throw new Error(`No GitNexus index found for ${repoPath}. Run gitnexus analyze first.`);\n    if (meta.incrementalInProgress) {\n      throw new Error('The structural index is incomplete. Run gitnexus analyze --force first.');\n    }\n\n    let lbugStat;\n    try {\n      lbugStat = await lstat(lbugPath);\n    } catch {\n      throw new Error(\n        `The LadybugDB graph store at ${lbugPath} is missing. Run gitnexus analyze first.`,\n      );\n    }\n    if (!lbugStat.isFile()) {\n      throw new Error(\n        `The LadybugDB graph store at ${lbugPath} is not a usable database file. Run gitnexus analyze first.`,\n      );\n    }\n\n    const { resolveEmbeddingIdentity } = await import('../core/embeddings/embedding-identity.js');\n    const identity = resolveEmbeddingIdentity();\n    let forceReembedNodeIds: ReadonlySet<string> | undefined;\n    let resumedFrom: EmbeddingCheckpoint | undefined;\n    if (meta.embeddingCheckpoint) {\n      const checkpoint = meta.embeddingCheckpoint;\n      const decision = decideEmbeddingResume(checkpoint, identity);\n      if (decision.action === 'abort') throw new Error(decision.error);\n      const identityDiffers =\n        checkpoint.provider !== identity.provider ||\n        checkpoint.model !== identity.model ||\n        checkpoint.dimensions !== identity.dimensions;\n      // `abandon` on a foreign identity drops the pending set only. Existing\n      // rows stay; sync would then embed the holes under the new identity and","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/cli/embeddings-sync.ts#L52-L88","documentation":"The LadybugDB path exists but lstat shows it is not a regular file (e.g. a directory, symlink to nothing handled elsewhere, or other special file), so it cannot be used as the graph database. Sync refuses to operate on unusable database paths.","triggerScenarios":"The expected database path is a directory (someone created a folder with the DB's name), a corrupted placeholder, a broken special file, or a symlink resolving to a non-file.","commonSituations":"Docker volume mounts replacing the DB path with a directory; a misconfigured storage path colliding with an existing directory; backup tools substituting placeholders.","solutions":["Inspect the reported path: `ls -la <lbugPath>`; remove/rename the directory or invalid entry that occupies the DB filename.","Run `gitnexus analyze` to recreate a valid database file, then re-run sync.","Fix any mount/volume configuration that substitutes a directory at the database path.","Do not hand-create files/dirs under the index storage directory."],"exampleFix":"// before\n$ ls -la .gitnexus/index.lbug   # drwxr-xr-x (directory!)\n// after\n$ rm -rf .gitnexus/index.lbug\n$ gitnexus analyze\n$ gitnexus embeddings-sync .","handlingStrategy":"validation","validationCode":"import { existsSync, lstatSync } from 'node:fs';\nfunction dbPathIsFile(p) {\n  try { return lstatSync(p).isFile(); } catch { return false; }\n}\n// if the DB path is a directory or special file, rebuild instead of syncing\nif (!dbPathIsExpectedFile) { /* rm the bad entry, then gitnexus analyze */ }","typeGuard":null,"tryCatchPattern":"try {\n  await gitnexus.embeddingsSync(repo);\n} catch (err) {\n  if (err.message.includes('not a usable database file')) {\n    // remove/fix the invalid entry at the reported path, then:\n    await run('gitnexus analyze');\n    await gitnexus.embeddingsSync(repo);\n  } else throw err;\n}","preventionTips":["Never create files or directories inside the index storage directory by hand.","Check Docker/Kubernetes volume mount targets don't shadow the DB file with a directory.","Inspect storage paths with `ls -la` after any storage reconfiguration.","Keep backup tooling from replacing index files with placeholders."],"tags":["database","file-type","embeddings","index"],"backgroundTag":"path-is-not-a-directory","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-09-15T23:29:44.066Z","contentChangedAt":"2026-09-15T23:29:44.066Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}