abhigyanpatwari/GitNexus · error · Error

Search index build failed with an integrity error and the an

Error message

Search index build failed with an integrity error and the analysis was aborted to avoid publishing a broken index: ${ftsResult.error}. The previous index is left intact. Re-run `gitnexus analyze`; if it persists, check the disk for space or corruption.

What it means

Thrown when `buildSearchIndexesOrDegrade` reports a failure classified as fatal by `ftsFailureIsFatal(ftsResult.failureClass, useAtomicSwap)`. This only fires on the atomic-swap build path: the graph was built into a throwaway staging DB, so throwing before the swap abandons the staging file and leaves the previous live index intact. The failure classes that trigger this are IO, rename, checkpoint, or corruption errors — genuinely broken builds on this disk, not transient concurrent-writer issues (the single-writer lock rules those out).

Source

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

        onIndexStart: options.verbose
          ? (table, indexName) => log(`FTS: creating ${table}.${indexName}`)
          : undefined,
        onIndexReady: options.verbose
          ? (table, indexName) => log(`FTS: ready ${table}.${indexName}`)
          : undefined,
      });
      if (ftsResult.ok) {
        progress('fts', 90, 'Search indexes ready');
      } else if (ftsFailureIsFatal(ftsResult.failureClass, useAtomicSwap)) {
        // #2658: an IO/rename/checkpoint/corruption failure while building FTS
        // is a genuinely broken build on this disk — not a concurrent writer
        // (the single-writer lock rules that out). ONLY fatal on the atomic-swap
        // path: the graph was built into a throwaway staging DB, so throwing
        // before the swap abandons the staging file and leaves the previous live
        // index intact. On an in-place build the live DB is already mutated and
        // cannot be rolled back by throwing (see ftsFailureIsFatal) — those
        // degrade in the branch below instead.
        throw new Error(
          `Search index build failed with an integrity error and the analysis was aborted ` +
            `to avoid publishing a broken index: ${ftsResult.error}. The previous index is ` +
            `left intact. Re-run \`gitnexus analyze\`; if it persists, check the disk for space ` +
            `or corruption.`,
        );
      } else {
        ftsReady = false;
        ftsSkipReason = 'build-failed';
        log(
          `FTS index build failed (${ftsResult.error}) — keyword search degraded this run. ` +
            'Graph and embeddings analysis completed successfully. Run `gitnexus analyze --repair-fts` to retry.',
        );
        progress('fts', 90, 'Search indexes skipped (build failed)');
      }
    } else {
      // For a missing runtime dependency (#2374) the file is present, so the
      // generic "install it with network access" tail in FTS_UNAVAILABLE_MESSAGE
      // contradicts the remedy's own "reinstalling will NOT help" (#2383 F2). Lead

View on GitHub (pinned to d540b00184)

Solutions

Re-run `gitnexus analyze` — the previous live index is intact, so this is safe.
Check disk space (`df -h`) — FTS index creation needs temporary space proportional to indexed content.
If the error persists, run a filesystem check (`fsck` / `chkdsk`) for disk corruption.
If on a cross-device tmp/live setup, ensure the staging and live paths are on the same filesystem (atomic swap uses rename, which fails across mount points).

Example fix

// before
gitnexus analyze
// error: Search index build failed with an integrity error...The previous index is left intact.
// after
df -h                           # check disk space
gitnexus analyze                # safe to re-run; previous index intact

Defensive patterns

Strategy: try-catch

Validate before calling

// Before analyze, check available disk space (FTS build needs temp space):
import { statfs } from 'fs/promises';
const stats = await statfs(repoPath);
const freeBytes = stats.bavail * stats.bsize;
if (freeBytes < 1024 * 1024 * 1024) { // < 1GB
  console.warn('Low disk space may cause FTS build integrity failures.');
}

Try / catch

try {
  await runAnalyze(options);
} catch (err) {
  if (err instanceof Error && err.message.includes('Search index build failed with an integrity error')) {
    console.error('Check disk space and filesystem health, then re-run `gitnexus analyze`.');
    console.error('The previous index is intact — re-running is safe.');
  }
  throw err;
}

Prevention

Ensure adequate free disk space before running `gitnexus analyze` — FTS indexing is space-proportional.
Keep the staging and live DB paths on the same filesystem (the atomic swap uses rename, which fails across mount points).
Run filesystem checks periodically on repositories with large indexes.

When it happens

Trigger: `ftsResult.ok` is false, `ftsFailureIsFatal` returns true because `useAtomicSwap` is true and the failure class is IO/rename/checkpoint/corruption. The analysis aborts before the atomic swap publishes the broken staging index.

Common situations: Disk full during FTS index creation; a filesystem rename failure on the atomic swap (cross-device link, permission denied); checkpoint corruption in the staging DB; a failing disk sector during large index writes.

Related errors

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