abhigyanpatwari/GitNexus · error · Error

Cannot repair FTS indexes: the LadybugDB FTS extension faile

Error message

Cannot repair FTS indexes: the LadybugDB FTS extension failed to load${ftsReason ? ` — ${ftsReason}` : ''}${remedyTail}

What it means

Thrown during `--repair-fts` when the FTS extension fails to load (`loadFTSExtension` returns false). The message includes the classified reason from `getExtensionCapabilities()` and routes Windows missing-dependency errors (error 126 — missing VC++ runtime or OpenSSL) to a specific remedy instead of the generic 'retry the network install' text that previously trapped users in a loop. Non-dependency failures get the generic install/network guidance.

Source

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

        // NOTE: deliberately the exported `getExtensionCapabilities()` rather
        // than `getFtsCapability()`. The #2383 regression tests stub that
        // export to inject a classified load failure; routing through the
        // helper bypasses the stub (ESM internal calls do not see a module
        // mock), and the classified VC++/ELF remedy silently degrades to
        // generic text — which is exactly the contradiction #2383 fixed.
        const rawFtsReason = getExtensionCapabilities().find((c) => c.name === 'fts')?.reason;
        const ftsReason = rawFtsReason?.replace(/\.$/, '');
        // A missing runtime dependency (Windows error 126, #2374) is not healed
        // by re-installing — the file is already present. Route that class to the
        // classified remedy (install VC++ redist / OpenSSL) instead of the old
        // "retry the network install" text that trapped the user in a loop.
        const { kind, remedy } = diagnoseExtensionLoad(rawFtsReason);
        const remedyTail =
          kind === 'missing_dependency'
            ? ` ${remedy}`
            : '. Retry with network access and GITNEXUS_LBUG_EXTENSION_INSTALL=auto to install it, ' +
              'or pre-install the extension file; run `gitnexus doctor` for live FTS status.';
        throw new Error(
          'Cannot repair FTS indexes: the LadybugDB FTS extension failed to load' +
            (ftsReason ? ` — ${ftsReason}` : '') +
            remedyTail,
        );
      }
      progress('fts', 85, 'Repairing search indexes...');
      const repairFailures = await createSearchFTSIndexes({
        onIndexStart: options.verbose
          ? (table, indexName) => log(`FTS: creating ${table}.${indexName}`)
          : undefined,
        onIndexReady: options.verbose
          ? (table, indexName) => log(`FTS: ready ${table}.${indexName}`)
          : undefined,
      });
      const missing = await verifySearchFTSIndexes(executeQuery);
      if (missing.length > 0) {
        // #2889: name WHY each index is missing when the build itself said so.
        // Repair now rebuilds every table it can before reporting, so the tables

View on GitHub (pinned to d540b00184)

Solutions

Run `gitnexus doctor` for a live FTS status and classified remedy.
If the reason is a missing runtime dependency (Windows error 126), install the Visual C++ Redistributable and/or OpenSSL as the remedy text directs.
If the extension simply was not installed, retry with network access and `GITNEXUS_LBUG_EXTENSION_INSTALL=auto`, or pre-install the extension file manually.
Re-run `gitnexus analyze --repair-fts` once the extension loads.

Example fix

// before (Windows, missing VC++ runtime)
gitnexus analyze --repair-fts
// error: ...FTS extension failed to load — ...missing_dependency
// after
// install VC++ Redistributable x64, then:
gitnexus analyze --repair-fts

Defensive patterns

Strategy: validation

Validate before calling

// Before repair-fts, check FTS extension health:
// (Run 'gitnexus doctor' programmatically or check capabilities)
import { getFtsCapability } from './lbug/extension-loader.js';
const fts = getFtsCapability();
if (!fts?.loaded) {
  console.error('FTS extension is not loaded. Run `gitnexus doctor` for remedies.');
  process.exit(1);
}

Type guard

import { getFtsCapability } from './lbug/extension-loader.js';
const isFtsExtensionLoaded = (): boolean => {
  const cap = getFtsCapability();
  return !!cap && cap.loaded;
};

Try / catch

try {
  await runAnalyze({ ...options, repairFts: true });
} catch (err) {
  if (err instanceof Error && err.message.includes('FTS extension failed to load')) {
    console.error('Install the required runtime dependency or extension. Run `gitnexus doctor`.');
  }
  throw err;
}

Prevention

Run `gitnexus doctor` after install to confirm the FTS extension loads before relying on it.
On Windows, install the Visual C++ Redistributable before first use.
In CI/Docker, ensure OpenSSL and the correct architecture's prebuild are present.

When it happens

Trigger: `repairFtsAvailable` is false after `loadFTSExtension(lbugPath, { policy })`. This happens when the native FTS shared library cannot be loaded: missing VC++ redistributable on Windows, missing OpenSSL on Linux, wrong architecture, or the extension was never downloaded and network access is unavailable.

Common situations: Windows without the Visual C++ Redistributable; a minimal Docker/CI image missing libssl; an air-gapped environment where the extension auto-download was blocked; an ARM machine with only x86 prebuilds available.

Related errors

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