abhigyanpatwari/GitNexus · error · Error

Cannot repair FTS indexes because this repository has not be

Error message

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`.

What it means

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.

Source

Thrown at gitnexus/src/core/run-analyze.ts:1112

  // Keep gitnexus.json and the legacy meta.json mirror in sync (fresher
  // indexedAt wins; nothing is deleted). Best-effort: loadMeta has its own
  // legacy fallback, so a reconciliation failure (read-only mount, full disk)
  // must never abort the analyze run — a repo that indexed fine read-only
  // before the rename must keep doing so.
  try {
    await reconcileMetadataFiles(repoPath);
  } catch (err) {
    const code = (err as NodeJS.ErrnoException)?.code;
    log(`Metadata reconciliation failed (non-critical${code ? `, ${code}` : ''}); continuing.`);
  }

  const existingMeta = await loadMeta(metaDir);

  // ── FTS-only repair path ────────────────────────────────────────────
  if (options.repairFts) {
    if (!existingMeta) {
      throw new Error(
        '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`.',
      );
    }
    if (existingMeta.incrementalInProgress) {
      // #2409 / tri-review 4669518496 (R6): a dirty flag means the previous
      // run died mid-writeback — the graph may be half-written and its WAL
      // possibly poisoned. This branch returns early, so the dirty-recovery
      // sidecar quarantine below would never run: repairing FTS now would
      // open the DB and replay that WAL pre-quarantine, and even a
      // survivable open would certify FTS over a half-written graph.
      throw new Error(
        'Cannot repair FTS indexes: the index is mid-incremental-recovery ' +
          '(a previous analyze run did not complete cleanly). ' +
          'Run `gitnexus analyze` first — it recovers the index automatically — ' +
          'then retry `--repair-fts`.',
      );
    }

View on GitHub (pinned to d540b00184)

Solutions

1. Run `gitnexus analyze` first to create the initial index — this also creates FTS indexes as part of the normal build
2. 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)
3. Verify the .gitnexus/ directory exists after the initial analyze — if it doesn't, check write permissions on the repo root

Example fix

# before — trying to repair FTS without an existing index
gitnexus analyze --repair-fts  # ERROR
# after — create the index first, then repair if needed
gitnexus analyze                # creates full index including FTS
gitnexus analyze --repair-fts   # now works (if FTS repair is needed)

// Check if the repo has been analyzed before running --repair-fts
import { stat } from 'fs/promises';
async function isAnalyzed(metaDir: string): Promise<boolean> {
  try {
    await stat(metaDir);
    return true;
  } catch {
    return false;
  }
}
// Before calling analyze with --repair-fts:
if (options.repairFts && !(await isAnalyzed(metaDir))) {
  throw new Error('Run `gitnexus analyze` first to create the initial index');
}

try {
  await runAnalyze(repoPath, { repairFts: true });
} catch (e) {
  if (e instanceof Error && e.message.includes('has not been analyzed yet')) {
    // Run full analyze first, then retry repair
    console.error('Run `gitnexus analyze` first, then retry --repair-fts');
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• --branch "${options.branch}" does not match the checked-out
• Malformed --shard arg '${malformed}' — expected --shard=<ind
• ${flag} must be a positive integer
• ${flag} is too large
• Failed to remove the LadybugDB index files — still present a

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