abhigyanpatwari/GitNexus · error · Error

Cannot repair FTS indexes: graph store at ${lbugPath} is ${f

Error message

Cannot repair FTS indexes: graph store at ${lbugPath} is ${foundType} (expected a file). Run `gitnexus analyze` (full) to rebuild from scratch.

What it means

Thrown during `--repair-fts` when `fs.lstat(lbugPath)` succeeds but the entry is not a regular file — it is a directory, symbolic link, socket, block/character device, FIFO, or other special file type. The LadybugDB graph store must be a single regular file; a non-file entry at that path indicates filesystem corruption, accidental directory creation, or a stray symlink, any of which would cause the database layer to malfunction if opened.

Source

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

        `Cannot repair FTS indexes: graph store at ${lbugPath} is missing. ` +
          'Run `gitnexus analyze` (full) to rebuild from scratch.',
      );
    }
    if (!lbugStat.isFile()) {
      const foundType = lbugStat.isDirectory()
        ? 'a directory'
        : lbugStat.isSymbolicLink()
          ? 'a symbolic link'
          : lbugStat.isSocket()
            ? 'a socket'
            : lbugStat.isBlockDevice()
              ? 'a block device'
              : lbugStat.isCharacterDevice()
                ? 'a character device'
                : lbugStat.isFIFO()
                  ? 'a FIFO'
                  : 'not a regular file';
      throw new Error(
        `Cannot repair FTS indexes: graph store at ${lbugPath} is ${foundType} (expected a file). ` +
          'Run `gitnexus analyze` (full) to rebuild from scratch.',
      );
    }
    try {
      await initLbug(lbugPath);
      // Gate on FTS availability BEFORE touching any index. createSearchFTSIndexes
      // now DROPs each index before recreating it (so schema changes reach existing
      // DBs); if the extension were unavailable, the drops would run and leave the
      // DB index-less, only failing at the create step. Fail loudly first — mirrors
      // the analyze path's `if (ftsAvailable)` gate below — so an unavailable
      // extension never destroys the existing indexes.
      const repairFtsAvailable = await loadFTSExtension(undefined, {
        policy: resolveAnalyzeInstallPolicy(),
      });
      if (!repairFtsAvailable) {
        // Surface the load-side reason (#2374): "not pre-installed" was wrong
        // and doctor never installed anything, so the old message trapped

View on GitHub (pinned to d540b00184)

Solutions

Remove the non-file entry at the reported path (e.g. `rm -rf <lbugPath>` if it's a directory).
Run `gitnexus analyze` (full) to rebuild the graph store as a proper file.
If the path is a symlink, verify where it points and either fix the target or remove the symlink before re-analyzing.

Example fix

// before
// .gitnexus/store.lbug is a directory or symlink → repair-fts fails
// after
rm -rf .gitnexus/store.lbug
gitnexus analyze               // creates a proper regular file
gitnexus analyze --repair-fts

Defensive patterns

Strategy: validation

Validate before calling

// Before repair-fts, verify lbugPath is a regular file:
import { stat } from 'fs/promises';
const s = await stat(lbugPath);
if (!s.isFile()) {
  console.error(`Expected a regular file at ${lbugPath}, got a different file type.`);
  process.exit(1);
}

Type guard

import { stat } from 'fs/promises';
const isRegularFile = async (p: string): Promise<boolean> => {
  try { return (await stat(p)).isFile(); } catch { return false; }
};

Try / catch

try {
  await runAnalyze({ ...options, repairFts: true });
} catch (err) {
  if (err instanceof Error && err.message.includes('expected a file')) {
    console.error('Remove the non-file entry and run `gitnexus analyze` to rebuild.');
  }
  throw err;
}

Prevention

Never create directories or symlinks at the graph store path.
After restoring from backup, verify `.gitnexus/` contains regular files, not directories.

When it happens

Trigger: `lbugStat.isFile()` returns false after a successful `lstat`. The found type is classified into a human-readable string (directory, symbolic link, socket, block device, character device, FIFO, or 'not a regular file').

Common situations: Someone manually created a directory named after the DB file (e.g. `mkdir .gitnexus/store.lbug`), a symlink was left pointing to a moved/deleted store, or a backup restore placed a directory where a file should be.

Related errors

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