abhigyanpatwari/GitNexus · warning · Error

Invalid GITNEXUS_FTS_CJK_SEGMENTATION "${process.env.GITNEXU

Error message

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

What it means

Thrown by `resolveFTSCjkSegmentation()` when the `GITNEXUS_FTS_CJK_SEGMENTATION` environment variable is set to a value not in the supported set (`none`, `bigram`). Validation happens once at analyze startup and caches the result, so an invalid value fails in milliseconds rather than partway through a run. The value is lowercased and trimmed before comparison, so only the two exact lowercase tokens are accepted.

Source

Thrown at gitnexus/src/core/search/cjk-segmentation.ts:149

 * interpolate a persisted `RepoMeta.cjkSegmentation` value into agent-visible
 * text (e.g. the MCP query-tool's mode-drift warning, #2339) must validate
 * with this first — that field comes from `meta.json`, a schema-less
 * `JSON.parse` of on-disk state inside the analyzed repo, not a trusted
 * input, so an unvalidated value could otherwise be echoed verbatim into
 * tool output an agent is expected to trust and act on.
 */
export const isSupportedCjkSegmentationMode = (value: unknown): value is string =>
  typeof value === 'string' && SUPPORTED_FTS_CJK_SEGMENTATION_MODES.has(value);

let resolvedCjkSegmentation: string | undefined;

/** Read + validate `GITNEXUS_FTS_CJK_SEGMENTATION`. Throws on an unsupported value. */
function resolveFTSCjkSegmentation(): string {
  const raw = process.env.GITNEXUS_FTS_CJK_SEGMENTATION?.trim().toLowerCase();
  if (!raw) return DEFAULT_FTS_CJK_SEGMENTATION;
  if (SUPPORTED_FTS_CJK_SEGMENTATION_MODES.has(raw)) return raw;

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

/**
 * Resolve + validate `GITNEXUS_FTS_CJK_SEGMENTATION` once, up front at analyze
 * startup, and cache it — mirrors `initialiseSearchFTSStemmer` so an invalid
 * value fails in milliseconds instead of partway through a run. The cached
 * value is what {@link getSearchFTSCjkSegmentation} returns for the rest of
 * the run, so config is read and validated in exactly one place.
 */
export function initialiseSearchFTSCjkSegmentation(): string {
  resolvedCjkSegmentation = resolveFTSCjkSegmentation();
  return resolvedCjkSegmentation;
}

/**

View on GitHub (pinned to d540b00184)

Solutions

  1. Set `GITNEXUS_FTS_CJK_SEGMENTATION` to either `none` (default, no CJK segmentation) or `bigram` (overlapping character bigrams for CJK search).
  2. Unset the variable entirely to accept the default (`none`).
  3. Check for typos: the value is case-insensitive but must be exactly one of the two supported tokens.

Example fix

# before
export GITNEXUS_FTS_CJK_SEGMENTATION=jieba
gitnexus analyze
# error: Invalid GITNEXUS_FTS_CJK_SEGMENTATION "jieba". Expected one of: bigram, none.
# after
export GITNEXUS_FTS_CJK_SEGMENTATION=bigram
gitnexus analyze
Defensive patterns

Strategy: validation

Validate before calling

// Validate the env var before starting analyze:
const SUPPORTED = new Set(['none', 'bigram']);
const raw = process.env.GITNEXUS_FTS_CJK_SEGMENTATION?.trim().toLowerCase();
if (raw && !SUPPORTED.has(raw)) {
  console.error(`Invalid GITNEXUS_FTS_CJK_SEGMENTATION. Use one of: ${[...SUPPORTED].join(', ')}`);
  process.exit(1);
}

Type guard

import { isSupportedCjkSegmentationMode } from './search/cjk-segmentation.js';
// isSupportedCjkSegmentationMode is exported and usable as a type guard:
const value: unknown = process.env.GITNEXUS_FTS_CJK_SEGMENTATION;
if (typeof value === 'string' && isSupportedCjkSegmentationMode(value)) {
  // safe to use
}

Try / catch

try {
  await runAnalyze(options);
} catch (err) {
  if (err instanceof Error && err.message.includes('Invalid GITNEXUS_FTS_CJK_SEGMENTATION')) {
    console.error('Set GITNEXUS_FTS_CJK_SEGMENTATION to "none" or "bigram", or unset it.');
  }
  throw err;
}

Prevention

When it happens

Trigger: `process.env.GITNEXUS_FTS_CJK_SEGMENTATION` is set to any string other than `none` or `bigram` (case-insensitive, after trimming). The `resolveFTSCjkSegmentation` function is called at analyze startup via the initialization path.

Common situations: Typo in the env var (`bigrams` instead of `bigram`); copied a value from documentation for a different library (e.g., `jieba`, which is deliberately excluded because it crashes the process); set the value to `true` or `1` thinking it's a boolean flag.

Related errors

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