FTS extension unavailable - cannot create FTS index ${tableN

Error message

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.

What it means

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.

Source

Thrown at gitnexus/src/core/lbug/lbug-adapter.ts:3109

 * @param indexName - Name for the FTS index
 * @param properties - List of properties to index (e.g., ['name', 'code'])
 * @param stemmer - Stemming algorithm (default: 'porter')
 */
export const createFTSIndex = async (
  tableName: string,
  indexName: string,
  properties: string[],
  stemmer: string = DEFAULT_FTS_STEMMER,
): Promise<void> => {
  if (!conn) {
    throw new Error('LadybugDB not initialized. Call initLbug first.');
  }

  const key = ftsIndexKey(tableName, indexName);
  if (ensuredFTSIndexes.has(key)) return;

  if (!(await loadFTSExtension())) {
    throw new Error(
      `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.',
    );
  }

  const propList = properties.map((p) => `'${p}'`).join(', ');
  const query = `CALL CREATE_FTS_INDEX('${tableName}', '${indexName}', [${propList}], stemmer := '${stemmer}')`;

  try {
    await queryAndDrain(conn, query);
    ensuredFTSIndexes.add(key);
  } catch (e: any) {
    if (e.message?.includes('already exists')) {
      ensuredFTSIndexes.add(key);
      return;
    }
    throw e;
  }

View on GitHub (pinned to d540b00184)

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

Defensive patterns

Strategy: validation

Validate before calling

// Check FTS extension availability before creating indexes
import { loadFTSExtension } from './fts-loader';
async function ftsAvailable(): Promise<boolean> {
  return await loadFTSExtension();
}
// Use before calling ensureFTSIndex
if (!(await ftsAvailable())) {
  console.error('FTS extension not available — run `gitnexus doctor`');
  // Fallback: skip FTS index creation, continue without semantic search
}

Try / catch

try {
  await ensureFTSIndex(tableName, indexName, properties);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('FTS extension unavailable')) {
    logger.warn('FTS extension unavailable — semantic search disabled for this run');
    // Continue without FTS; the index will be created when the extension is available
    return;
  }
  throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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