abhigyanpatwari/GitNexus · warning · Error

Invalid GITNEXUS_FTS_STEMMER "${process.env.GITNEXUS_FTS_STE

Error message

Invalid GITNEXUS_FTS_STEMMER "${process.env.GITNEXUS_FTS_STEMMER}". Expected one of: ${[...SUPPORTED_FTS_STEMMERS].sort().join(', ')}.

What it means

Thrown by `resolveFTSStemmer()` when the `GITNEXUS_FTS_STEMMER` environment variable is set to a value not in `SUPPORTED_FTS_STEMMERS`. The supported set mirrors the stemmer tokens shipped by the LadybugDB FTS extension (28 values including `none`, `porter`, and language names like `english`, `french`). Validation runs once at startup via `initialiseSearchFTSStemmer()` and caches the result, so an invalid value fails in milliseconds instead of ~85% into a run after expensive parsing.

Source

Thrown at gitnexus/src/core/search/fts-indexes.ts:171

  'swedish',
  'tamil',
  'turkish',
]);

export interface CreateSearchFTSIndexesOptions {
  onIndexStart?: (table: string, indexName: string) => void;
  onIndexReady?: (table: string, indexName: string) => void;
}

let resolvedStemmer: string | undefined;

/** Read + validate `GITNEXUS_FTS_STEMMER`. Throws on an unsupported value. */
function resolveFTSStemmer(): string {
  const raw = process.env.GITNEXUS_FTS_STEMMER?.trim().toLowerCase();
  if (!raw) return DEFAULT_FTS_STEMMER;
  if (SUPPORTED_FTS_STEMMERS.has(raw)) return raw;

  throw new Error(
    `Invalid GITNEXUS_FTS_STEMMER "${process.env.GITNEXUS_FTS_STEMMER}". ` +
      `Expected one of: ${[...SUPPORTED_FTS_STEMMERS].sort().join(', ')}.`,
  );
}

/**
 * Resolve + validate `GITNEXUS_FTS_STEMMER` once, up front at analyze startup,
 * and cache it. An invalid value throws here — in milliseconds — instead of
 * ~85% into a run (after the expensive parse/scope-resolution work). The cached
 * value is what {@link getSearchFTSStemmer} returns for the rest of the run, so
 * config is read and validated in exactly one place.
 */
export function initialiseSearchFTSStemmer(): string {
  resolvedStemmer = resolveFTSStemmer();
  return resolvedStemmer;
}

/**

View on GitHub (pinned to d540b00184)

Solutions

Set `GITNEXUS_FTS_STEMMER` to one of the supported values listed in the error message (e.g., `english`, `porter`, `none`).
Unset the variable to accept the default stemmer.
If using a language-specific stemmer, verify it's in the supported set — the error lists every accepted value sorted alphabetically.

Example fix

# before
export GITNEXUS_FTS_STEMMER=enlgish
gitnexus analyze
# error: Invalid GITNEXUS_FTS_STEMMER "enlgish". Expected one of: arabic, basque, ...
# after
export GITNEXUS_FTS_STEMMER=english
gitnexus analyze

Defensive patterns

Strategy: validation

Validate before calling

// Validate the env var before starting analyze:
import { SUPPORTED_FTS_STEMMERS } from './search/fts-indexes.js';
const raw = process.env.GITNEXUS_FTS_STEMMER?.trim().toLowerCase();
if (raw && !SUPPORTED_FTS_STEMMERS.has(raw)) {
  console.error(`Invalid stemmer. Supported: ${[...SUPPORTED_FTS_STEMMERS].sort().join(', ')}`);
  process.exit(1);
}

Type guard

import { SUPPORTED_FTS_STEMMERS } from './search/fts-indexes.js';
const isValidStemmer = (value: unknown): value is string =>
  typeof value === 'string' && SUPPORTED_FTS_STEMMERS.has(value.trim().toLowerCase());

Try / catch

try {
  await runAnalyze(options);
} catch (err) {
  if (err instanceof Error && err.message.includes('Invalid GITNEXUS_FTS_STEMMER')) {
    console.error('Check supported stemmers in the error message. Default is usually fine.');
  }
  throw err;
}

Prevention

Import `SUPPORTED_FTS_STEMMERS` from `fts-indexes.ts` to validate in your own scripts.
When upgrading LadybugDB versions, re-check the supported stemmer set — it mirrors the extension's capabilities.
Unset the variable if you don't need a specific stemmer; the default is sensible.

When it happens

Trigger: `process.env.GITNEXUS_FTS_STEMMER` is set to any string not in the supported set (case-insensitive, after trimming). The `resolveFTSStemmer` function is called at analyze startup.

Common situations: Typo (`enlgish` instead of `english`); using a Porter stemmer variant name (`porter2`, `snowball`) that the extension doesn't recognize; using an uppercase value from copy-paste that happens to work elsewhere but not here (though this code lowercases); setting a language the extension version doesn't ship (after a LadybugDB downgrade).

Related errors

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