{"record":{"id":"b3aa390871588ec6","repo":"abhigyanpatwari/GitNexus","slug":"the-structural-index-is-incomplete-run-gitnexus-analyze","errorCode":null,"errorMessage":"The structural index is incomplete. Run gitnexus analyze --force first.","messagePattern":"The structural index is incomplete\\. Run gitnexus analyze --force first\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/cli/embeddings-sync.ts","lineNumber":58,"sourceCode":"\n/** Add missing embeddings directly to a healthy index, checkpointing periodically. */\nexport const embeddingsSyncCommand = async (inputPath?: string): Promise<void> => {\n  const repoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());\n  if (!repoPath) throw new Error('Not inside a git repository. Pass a repository path.');\n\n  const { lbugPath, metaPath } = getStoragePaths(repoPath);\n  const metaDir = path.dirname(metaPath);\n  const lock = await acquireIndexLock(metaDir);\n  try {\n    requireExclusiveIndexLock(\n      lock,\n      `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();","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/cli/embeddings-sync.ts#L40-L76","documentation":"The index metadata exists but has incrementalInProgress set, meaning an incremental analyze did not finish and the structural index is incomplete. Embedding sync refuses to run against a partial graph because embeddings reference nodes that may not exist yet.","triggerScenarios":"A previous `gitnexus analyze --incremental` (or interrupted analyze) left meta.incrementalInProgress=true; running embeddings sync before completing a structural rebuild.","commonSituations":"An analyze run was killed mid-way (CI timeout, Ctrl+C, crash); a concurrent analyze was aborted; the metadata flag persisted after an unclean shutdown.","solutions":["Run `gitnexus analyze --force` to complete a full structural rebuild, then re-run the embeddings sync.","Check no other analyze process is currently running against the same index.","If the flag is stale after a crash, the forced rebuild will reset it.","Avoid killing analyze mid-run; let it complete before switching to embeddings sync."],"exampleFix":"// before\n$ gitnexus embeddings-sync .   # Error: structural index is incomplete\n// after\n$ gitnexus analyze --force\n$ gitnexus embeddings-sync .","handlingStrategy":"validation","validationCode":"// Detect a stale/unfinished incremental run before syncing:\nimport { readFileSync, existsSync } from 'node:fs';\nfunction indexIncomplete(repoPath) {\n  const metaPath = join(repoPath, '.gitnexus');\n  if (!existsSync(metaPath)) return true;\n  try {\n    const meta = JSON.parse(readFileSync(metaPath, 'utf8'));\n    return meta.incrementalInProgress === true;\n  } catch { return true; }\n}\nif (indexIncomplete(repo)) await run('gitnexus analyze --force');","typeGuard":null,"tryCatchPattern":"try {\n  await gitnexus.embeddingsSync(repo);\n} catch (err) {\n  if (err.message.includes('structural index is incomplete')) {\n    await run('gitnexus analyze --force');\n    await gitnexus.embeddingsSync(repo);\n  } else throw err;\n}","preventionTips":["Never kill `gitnexus analyze` mid-run (avoid CI timeouts; raise job time limits).","After a crashed analyze, always finish with `gitnexus analyze --force` before other index operations.","Serialize index operations — don't run embeddings sync concurrently with analyze.","Monitor CI jobs for canceled analyze steps and re-run the full analyze afterwards."],"tags":["index","embeddings","incomplete-state"],"backgroundTag":"invalid-state-transition","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"}