{"record":{"id":"e68baccdbf00a6aa","repo":"abhigyanpatwari/GitNexus","slug":"cannot-repair-fts-indexes-because-this-repository","errorCode":null,"errorMessage":"Cannot repair FTS indexes because this repository has not been analyzed yet. Run `gitnexus analyze` first to create the initial index, then retry `--repair-fts`.","messagePattern":"Cannot repair FTS indexes because this repository has not been analyzed yet\\. Run `gitnexus analyze` first to create the initial index, then retry `--repair-fts`\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/run-analyze.ts","lineNumber":1112,"sourceCode":"\n  // Keep gitnexus.json and the legacy meta.json mirror in sync (fresher\n  // indexedAt wins; nothing is deleted). Best-effort: loadMeta has its own\n  // legacy fallback, so a reconciliation failure (read-only mount, full disk)\n  // must never abort the analyze run — a repo that indexed fine read-only\n  // before the rename must keep doing so.\n  try {\n    await reconcileMetadataFiles(repoPath);\n  } catch (err) {\n    const code = (err as NodeJS.ErrnoException)?.code;\n    log(`Metadata reconciliation failed (non-critical${code ? `, ${code}` : ''}); continuing.`);\n  }\n\n  const existingMeta = await loadMeta(metaDir);\n\n  // ── FTS-only repair path ────────────────────────────────────────────\n  if (options.repairFts) {\n    if (!existingMeta) {\n      throw new Error(\n        'Cannot repair FTS indexes because this repository has not been analyzed yet. ' +\n          'Run `gitnexus analyze` first to create the initial index, then retry `--repair-fts`.',\n      );\n    }\n    if (existingMeta.incrementalInProgress) {\n      // #2409 / tri-review 4669518496 (R6): a dirty flag means the previous\n      // run died mid-writeback — the graph may be half-written and its WAL\n      // possibly poisoned. This branch returns early, so the dirty-recovery\n      // sidecar quarantine below would never run: repairing FTS now would\n      // open the DB and replay that WAL pre-quarantine, and even a\n      // survivable open would certify FTS over a half-written graph.\n      throw new Error(\n        'Cannot repair FTS indexes: the index is mid-incremental-recovery ' +\n          '(a previous analyze run did not complete cleanly). ' +\n          'Run `gitnexus analyze` first — it recovers the index automatically — ' +\n          'then retry `--repair-fts`.',\n      );\n    }","sourceCodeStart":1094,"sourceCodeEnd":1130,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/run-analyze.ts#L1094-L1130","documentation":"Thrown by the analyze command's FTS-only repair path (--repair-fts) when loadMeta(metaDir) returns null — meaning the repository has never been analyzed and no index metadata exists. The FTS repair path needs an existing index to repair; it cannot create FTS indexes from scratch (that requires a full analyze run). This is a precondition guard: --repair-fts is a maintenance operation on an existing index, not a bootstrap operation. The error directs the user to run a full `gitnexus analyze` first.","triggerScenarios":"Running `gitnexus analyze --repair-fts` on a repository that has never been analyzed (no .gitnexus/ metadata directory or no meta file within it); running it after the .gitnexus/ directory was deleted; running it on a fresh clone where no index exists. The loadMeta call returns null when no metadata file is found.","commonSituations":"A new user who heard about FTS repair and tries it before doing a first analyze; a developer who cleared the .gitnexus/ directory and tries to repair without rebuilding first; confusion between `analyze` (creates index) and `analyze --repair-fts` (repairs FTS indexes within an existing index).","solutions":["Run `gitnexus analyze` first to create the initial index — this also creates FTS indexes as part of the normal build","After the initial analyze completes, run `gitnexus analyze --repair-fts` if you specifically need to rebuild just the FTS indexes (e.g. after a stemmer change)","Verify the .gitnexus/ directory exists after the initial analyze — if it doesn't, check write permissions on the repo root"],"exampleFix":"# before — trying to repair FTS without an existing index\ngitnexus analyze --repair-fts  # ERROR\n# after — create the index first, then repair if needed\ngitnexus analyze                # creates full index including FTS\ngitnexus analyze --repair-fts   # now works (if FTS repair is needed)","handlingStrategy":"validation","validationCode":"// Check if the repo has been analyzed before running --repair-fts\nimport { stat } from 'fs/promises';\nasync function isAnalyzed(metaDir: string): Promise<boolean> {\n  try {\n    await stat(metaDir);\n    return true;\n  } catch {\n    return false;\n  }\n}\n// Before calling analyze with --repair-fts:\nif (options.repairFts && !(await isAnalyzed(metaDir))) {\n  throw new Error('Run `gitnexus analyze` first to create the initial index');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runAnalyze(repoPath, { repairFts: true });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('has not been analyzed yet')) {\n    // Run full analyze first, then retry repair\n    console.error('Run `gitnexus analyze` first, then retry --repair-fts');\n  }\n  throw e;\n}","preventionTips":["Always run `gitnexus analyze` (full) as the first step on a new repo — it creates FTS indexes","Use `--repair-fts` only as a maintenance operation on an existing, healthy index","Document the analyze → repair-fts workflow in onboarding guides","In CI, run a full analyze as a prerequisite before any repair-fts step"],"tags":["analyze","repair-fts","precondition","cli","metadata"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}