{"record":{"id":"d69dde9284c2d84a","repo":"abhigyanpatwari/GitNexus","slug":"fts-extension-unavailable-cannot-create-fts-inde","errorCode":null,"errorMessage":"FTS extension unavailable - cannot create FTS index ${tableName}.${indexName}. Run `gitnexus doctor` and ensure the LadybugDB FTS extension is installed and loadable on this machine.","messagePattern":"FTS extension unavailable - cannot create FTS index (.+?)\\.(.+?)\\. Run `gitnexus doctor` and ensure the LadybugDB FTS extension is installed and loadable on this machine\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/lbug/lbug-adapter.ts","lineNumber":3470,"sourceCode":" * @param indexName - Name for the FTS index\n * @param properties - List of properties to index (e.g., ['name', 'code'])\n * @param stemmer - Stemming algorithm (default: 'porter')\n */\nexport const createFTSIndex = async (\n  tableName: string,\n  indexName: string,\n  properties: string[],\n  stemmer: string = DEFAULT_FTS_STEMMER,\n): Promise<void> => {\n  if (!conn) {\n    throw new Error('LadybugDB not initialized. Call initLbug first.');\n  }\n\n  const key = ftsIndexKey(tableName, indexName);\n  if (ensuredFTSIndexes.has(key)) return;\n\n  if (!(await loadFTSExtension())) {\n    throw new Error(\n      `FTS extension unavailable - cannot create FTS index ${tableName}.${indexName}. ` +\n        'Run `gitnexus doctor` and ensure the LadybugDB FTS extension is installed and loadable on this machine.',\n    );\n  }\n\n  const propList = properties.map((p) => `'${p}'`).join(', ');\n  const query = `CALL CREATE_FTS_INDEX('${tableName}', '${indexName}', [${propList}], stemmer := '${stemmer}')`;\n\n  try {\n    await queryAndDrain(conn, query);\n    ensuredFTSIndexes.add(key);\n  } catch (e: any) {\n    if (e.message?.includes('already exists')) {\n      ensuredFTSIndexes.add(key);\n      return;\n    }\n    throw e;\n  }","sourceCodeStart":3452,"sourceCodeEnd":3488,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/core/lbug/lbug-adapter.ts#L3452-L3488","documentation":"createFTSIndex (gitnexus/src/core/lbug/lbug-adapter.ts:3109) refuses to run CREATE_FTS_INDEX when loadFTSExtension() returns false — the LadybugDB FTS extension binary could not be installed or loaded in this environment (missing file, wrong platform, missing runtime dependency such as OpenSSL or the VC++ runtime, or a blocked install). Creating the index without the extension is impossible, so the call fails with doctor guidance.","triggerScenarios":"First analyze on a machine where the FTS extension is not installed and auto-install cannot fetch it (offline, proxy-blocked, extension server unreachable), or the binary fails to load (missing OS dependency, wrong architecture); calling createFTSIndex/ensureFTSIndex before any successful load.","commonSituations":"Air-gapped CI containers; slim Docker images lacking the runtime libs the extension links against; a moved or corrupted extension cache directory; read-only HOME preventing INSTALL from writing.","solutions":["Run `gitnexus doctor` — it diagnoses and reports the extension state on this machine","Ensure the machine can reach the LadybugDB extension server or pre-install the FTS extension into the cache, then retry","Install the missing runtime dependency the load diagnosis names (OpenSSL / VC++ runtime) and retry","If FTS is not needed in this environment, rebuild without it: gitnexus analyze --force"],"exampleFix":"// before — assumes FTS is available and throws when it is not\nawait createFTSIndex('CodeSymbol', 'fts_name', ['name']);\n\n// after — probe first and degrade gracefully\nif (!(await loadFTSExtension(undefined, { policy: 'load-only' }))) {\n  logger.warn('FTS unavailable — search falls back to exact scan');\n} else {\n  await createFTSIndex('CodeSymbol', 'fts_name', ['name']);\n}","handlingStrategy":"fallback","validationCode":"// probe before creating FTS indexes; degrade instead of throwing\nconst ftsOk = await loadFTSExtension(undefined, { policy: 'load-only' });\nif (!ftsOk) {\n  logger.warn('FTS extension unavailable — using exact scan for search');\n}","typeGuard":"const isFtsUnavailable = (e: unknown): boolean =>\n  e instanceof Error && e.message.startsWith('FTS extension unavailable');","tryCatchPattern":"try {\n  await createFTSIndex(tableName, indexName, properties);\n} catch (e) {\n  if (isFtsUnavailable(e)) {\n    // fall back to the non-FTS search path rather than failing the analyze\n    logger.warn(`skipping FTS index ${indexName}: ${e.message}`);\n  } else {\n    throw e;\n  }\n}","preventionTips":["Run `gitnexus doctor` during environment provisioning to catch extension problems early","Pre-install LadybugDB extensions in CI images instead of relying on network installs at analyze time","Install the OS runtime dependencies (OpenSSL / VC++ redistributable) the extension links against"],"tags":["gitnexus","ladybugdb","fts","extension","doctor","offline-install"],"backgroundTag":"extension-load-failure","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}