{"record":{"id":"272d91a0d8922261","repo":"abhigyanpatwari/GitNexus","slug":"cannot-repair-fts-indexes-the-ladybugdb-fts-exten","errorCode":null,"errorMessage":"Cannot repair FTS indexes: the LadybugDB FTS extension failed to load${ftsReason ? ` — ${ftsReason}` : ''}${remedyTail}","messagePattern":"Cannot repair FTS indexes: the LadybugDB FTS extension failed to load(.+?)` : ''\\}(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/run-analyze.ts","lineNumber":1192,"sourceCode":"        // NOTE: deliberately the exported `getExtensionCapabilities()` rather\n        // than `getFtsCapability()`. The #2383 regression tests stub that\n        // export to inject a classified load failure; routing through the\n        // helper bypasses the stub (ESM internal calls do not see a module\n        // mock), and the classified VC++/ELF remedy silently degrades to\n        // generic text — which is exactly the contradiction #2383 fixed.\n        const rawFtsReason = getExtensionCapabilities().find((c) => c.name === 'fts')?.reason;\n        const ftsReason = rawFtsReason?.replace(/\\.$/, '');\n        // A missing runtime dependency (Windows error 126, #2374) is not healed\n        // by re-installing — the file is already present. Route that class to the\n        // classified remedy (install VC++ redist / OpenSSL) instead of the old\n        // \"retry the network install\" text that trapped the user in a loop.\n        const { kind, remedy } = diagnoseExtensionLoad(rawFtsReason);\n        const remedyTail =\n          kind === 'missing_dependency'\n            ? ` ${remedy}`\n            : '. Retry with network access and GITNEXUS_LBUG_EXTENSION_INSTALL=auto to install it, ' +\n              'or pre-install the extension file; run `gitnexus doctor` for live FTS status.';\n        throw new Error(\n          'Cannot repair FTS indexes: the LadybugDB FTS extension failed to load' +\n            (ftsReason ? ` — ${ftsReason}` : '') +\n            remedyTail,\n        );\n      }\n      progress('fts', 85, 'Repairing search indexes...');\n      const repairFailures = await createSearchFTSIndexes({\n        onIndexStart: options.verbose\n          ? (table, indexName) => log(`FTS: creating ${table}.${indexName}`)\n          : undefined,\n        onIndexReady: options.verbose\n          ? (table, indexName) => log(`FTS: ready ${table}.${indexName}`)\n          : undefined,\n      });\n      const missing = await verifySearchFTSIndexes(executeQuery);\n      if (missing.length > 0) {\n        // #2889: name WHY each index is missing when the build itself said so.\n        // Repair now rebuilds every table it can before reporting, so the tables","sourceCodeStart":1174,"sourceCodeEnd":1210,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/run-analyze.ts#L1174-L1210","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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."],"exampleFix":"// before (Windows, missing VC++ runtime)\ngitnexus analyze --repair-fts\n// error: ...FTS extension failed to load — ...missing_dependency\n// after\n// install VC++ Redistributable x64, then:\ngitnexus analyze --repair-fts","handlingStrategy":"validation","validationCode":"// Before repair-fts, check FTS extension health:\n// (Run 'gitnexus doctor' programmatically or check capabilities)\nimport { getFtsCapability } from './lbug/extension-loader.js';\nconst fts = getFtsCapability();\nif (!fts?.loaded) {\n  console.error('FTS extension is not loaded. Run `gitnexus doctor` for remedies.');\n  process.exit(1);\n}","typeGuard":"import { getFtsCapability } from './lbug/extension-loader.js';\nconst isFtsExtensionLoaded = (): boolean => {\n  const cap = getFtsCapability();\n  return !!cap && cap.loaded;\n};","tryCatchPattern":"try {\n  await runAnalyze({ ...options, repairFts: true });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('FTS extension failed to load')) {\n    console.error('Install the required runtime dependency or extension. Run `gitnexus doctor`.');\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["fts","native-extension","windows","dependencies","environment"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}