Cannot repair FTS indexes: the LadybugDB FTS extension…

Error message

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

What it means

runFullAnalysisInner throws when the LadybugDB FTS extension fails to load during --repair-fts, including an optional load-failure reason and a remedy tail that depends on the extension kind (classified-load remedy or a network/pre-install remedy plus `gitnexus doctor` for live FTS status). FTS repair cannot proceed without the extension binary.

Solutions

Run `gitnexus doctor` for live FTS status to see the concrete load failure.
Re-run with network access and GITNEXUS_LBUG_EXTENSION_INSTALL=auto to install the extension.
Pre-install the extension file matching your platform/arch if the network is unavailable.
If the binary is corrupt or for the wrong arch, delete the cached extension and reinstall.

Example fix

// before (offline, default install mode)
gitnexus analyze --repair-fts
// after
GITNEXUS_LBUG_EXTENSION_INSTALL=auto gitnexus analyze --repair-fts

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: check live FTS status before attempting repair
import { execSync } from 'node:child_process';
console.log(execSync('gitnexus doctor').toString());

Try / catch

try {
  await runAnalyze({ repairFts: true });
} catch (err) {
  if (err instanceof Error && err.message.includes('FTS extension failed to load')) {
    console.error('Pre-install the FTS extension or set GITNEXUS_LBUG_EXTENSION_INSTALL=auto with network access.');
  } else throw err;
}

Prevention

Pre-install the LadybugDB FTS extension for your platform in air-gapped environments.
Run `gitnexus doctor` after upgrades to verify FTS extension status.
Keep the cached extension arch in sync when switching machines/containers.

When it happens

Trigger: Running `gitnexus analyze --repair-fts` when the LadybugDB FTS extension is not installed locally and cannot be downloaded (no network, GITNEXUS_LBUG_EXTENSION_INSTALL not set to auto), or the extension file is present but fails to load (wrong platform/arch build).

Common situations: Air-gapped or restricted-network CI where the extension was never pre-installed; upgrading platforms (e.g. ARM vs x64) leaving a stale extension binary; GITNEXUS_LBUG_EXTENSION_INSTALL left at its default instead of 'auto'.

Related errors

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

Appendix: source

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

        // 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 inspectPath = extractExtensionPath(rawFtsReason);
        const { kind, remedy } = diagnoseExtensionLoad(
          rawFtsReason,
          'FTS',
          inspectPath,
          resolveFtsVersionPair(inspectPath),
        );
        const remedyTail = usesClassifiedLoadRemedy(kind)
          ? ` ${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...');
      // Restamp before CREATE so a second native abort still has in-place
      // FTS dirty evidence after persist cleared the first stamp.
      try {
        const latestBeforeCreate = (await loadMeta(metaDir)) ?? existingMeta;
        await saveMeta(metaDir, {
          ...latestBeforeCreate,
          incrementalInProgress: buildFtsDirtyStamp({
            prior: latestBeforeCreate.incrementalInProgress,
            writePlan: 'in-place',
            checkpointSucceeded: true,
          }),
        });

View on GitHub (pinned to ac9a4e9abd)