{"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":3109,"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":3091,"sourceCodeEnd":3127,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/lbug/lbug-adapter.ts#L3091-L3127","documentation":"Thrown when ensureFTSIndex calls loadFTSExtension() and it returns false, meaning the LadybugDB Full-Text Search extension could not be loaded into the current process. The FTS extension is a separate native module that provides CREATE_FTS_INDEX capabilities for semantic code search. Without it, GitNexus cannot create full-text indexes on node properties (names, signatures, file paths). The error fires before any FTS index creation is attempted and is cached via an ensuredFTSIndexes set so subsequent calls for the same index short-circuit.","triggerScenarios":"Calling ensureFTSIndex(tableName, indexName, properties) when the FTS extension native module is missing from the LadybugDB installation, has incorrect file permissions, is compiled for a different architecture/platform, or its shared library dependencies are unavailable. Also triggered if LadybugDB was installed without the FTS extension package.","commonSituations":"Fresh GitNexus installation where the FTS extension wasn't included in the package; a LadybugDB version upgrade that changed the extension loading mechanism; running on a platform (e.g. Alpine Linux with musl) where the extension's glibc-linked binary won't load; Docker container missing the extension's shared library dependencies; a partial/corrupted LadybugDB install.","solutions":["Run `gitnexus doctor` — it diagnoses FTS extension availability and installation health","Reinstall LadybugDB: `npm install @ladybugdb/core` in the gitnexus/ directory to ensure the FTS extension is present","Check the extension's shared library dependencies with `ldd` (Linux) — install any missing system libraries (e.g. libstdc++)","On Alpine Linux/musl, use a glibc-based image or compile LadybugDB from source for musl","Verify the extension file has correct permissions and is readable by the GitNexus process"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Check FTS extension availability before creating indexes\nimport { loadFTSExtension } from './fts-loader';\nasync function ftsAvailable(): Promise<boolean> {\n  return await loadFTSExtension();\n}\n// Use before calling ensureFTSIndex\nif (!(await ftsAvailable())) {\n  console.error('FTS extension not available — run `gitnexus doctor`');\n  // Fallback: skip FTS index creation, continue without semantic search\n}","typeGuard":null,"tryCatchPattern":"try {\n  await ensureFTSIndex(tableName, indexName, properties);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('FTS extension unavailable')) {\n    logger.warn('FTS extension unavailable — semantic search disabled for this run');\n    // Continue without FTS; the index will be created when the extension is available\n    return;\n  }\n  throw e;\n}","preventionTips":["Run `gitnexus doctor` after installation to verify FTS extension health","Reinstall @ladybugdb/core if the FTS extension is missing","On Linux, check shared library dependencies with ldd on the extension .so file","In Docker, use a base image with glibc (not Alpine musl) unless you compile LadybugDB for musl"],"tags":["fts","ladybugdb","native-extension","search","doctor"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}