{"record":{"id":"f00fdcc82b0d58fa","repo":"abhigyanpatwari/GitNexus","slug":"analysis-did-not-finalize-for-repopath-index","errorCode":null,"errorMessage":"Analysis did not finalize for ${repoPath}: ${INDEX_METADATA_FILE} was not written to ${path.join(storagePath, INDEX_METADATA_FILE)}. The on-disk index is incomplete and was not registered. Re-run \"gitnexus analyze\" — if the problem persists, inspect ${storagePath} for a stale lbug.wal that signals an aborted write.","messagePattern":"Analysis did not finalize for (.+?): (.+?) was not written to (.+?)\\. The on-disk index is incomplete and was not registered\\. Re-run \"gitnexus analyze\" — if the problem persists, inspect (.+?) for a stale lbug\\.wal that signals an aborted write\\.","errorType":"exception","errorClass":"AnalysisNotFinalizedError","httpStatus":null,"severity":"error","filePath":"gitnexus/src/storage/repo-manager.ts","lineNumber":1204,"sourceCode":" *      (the primary metadata file; the legacy `meta.json` mirror is not\n *      sufficient — a finalized analyze always writes the primary).\n *   2. The global registry (`getGlobalRegistryPath()`) must contain an\n *      entry whose canonical path matches `repoPath`.\n *\n * Throws {@link AnalysisNotFinalizedError} on the first failure with the\n * specific missing artifact. Pure read — does not mutate disk state.\n *\n * Callers must skip this assertion on the `alreadyUpToDate` early-return\n * path, where the rebuild was deliberately not run.\n */\nexport const assertAnalysisFinalized = async (repoPath: string): Promise<void> => {\n  const resolved = path.resolve(repoPath);\n  const { storagePath, metaPath } = getStoragePaths(resolved);\n\n  try {\n    await fs.access(metaPath);\n  } catch {\n    throw new AnalysisNotFinalizedError(resolved, storagePath, 'meta', getGlobalRegistryPath());\n  }\n\n  if (!(await isRepoRegistered(resolved))) {\n    throw new AnalysisNotFinalizedError(\n      resolved,\n      storagePath,\n      'registry-entry',\n      getGlobalRegistryPath(),\n    );\n  }\n};\n\n/**\n * Thrown by {@link assertSafeStoragePath} when a registry entry's\n * `storagePath` does NOT point at the expected `<entry.path>/.gitnexus`\n * subfolder. CLI destructive commands (`remove`, `clean --all`) should\n * catch this and exit non-zero without deleting anything — the usual\n * cause is a corrupted or hand-edited `~/.gitnexus/registry.json`, and","sourceCodeStart":1186,"sourceCodeEnd":1222,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/aac7515d2a8c50a1f8f923c6fb77218b333560d6/gitnexus/src/storage/repo-manager.ts#L1186-L1222","documentation":"After analyze writes an index, assertAnalysisFinalized verifies the finality artifacts before the run is considered done. This variant ('meta'): gitnexus.json (INDEX_METADATA_FILE) was never written into the repo's .gitnexus storage path — the analysis crashed or was interrupted before finalization, so the on-disk index is incomplete and deliberately was not registered.","triggerScenarios":"analyze is killed (OOM, SIGKILL, CI timeout) between writing index data and sealing metadata; a LadybugDB write aborted leaving a stale lbug.wal; disk-full blocking the final metadata write.","commonSituations":"Large repos killed near the end of indexing; container memory limits; full disks; machines sleeping mid-run.","solutions":["Re-run gitnexus analyze — the pipeline rebuilds and re-seals the index","If it persists, inspect <repo>/.gitnexus for a stale lbug.wal (aborted-write signal) and clean the storage (gitnexus clean) before re-indexing","Free disk space and raise memory/CI timeouts so the run can complete","Check for concurrent analyze runs that raced the write (see the index-lock timeout errors)"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import fs from 'node:fs';\nimport path from 'node:path';\nfunction indexFinalized(repo: string): boolean {\n  return fs.existsSync(path.join(repo, '.gitnexus', 'gitnexus.json'));\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runAnalyze(repo);\n} catch (e) {\n  if (e?.name === 'AnalysisNotFinalizedError' && e.kind === 'meta') {\n    await cleanStorage(repo); // removes stale lbug.wal from the aborted write\n    return runAnalyze(repo); // one clean rebuild\n  }\n  throw e;\n}","preventionTips":["Ensure analyze runs to completion: adequate CI timeouts, memory limits, disk space","After any interrupted run, check for a stale lbug.wal in the storage dir and clean before re-indexing","Never read an index whose gitnexus.json is missing — it is incomplete by definition"],"tags":["indexing","metadata","crash-recovery","data-integrity"],"backgroundTag":"incomplete-index-write","analyzedSha":"aac7515d2a8c50a1f8f923c6fb77218b333560d6","analyzedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}