abhigyanpatwari/GitNexus · error · Error

${name} must be a positive integer, got "${value}"

Error message

${name} must be a positive integer, got "${value}"

What it means

Thrown by parsePositiveInt() in config.ts when an embedding config integer env var (GITNEXUS_EMBEDDING_BATCH_SIZE, GITNEXUS_EMBEDDING_SUB_BATCH_SIZE, or GITNEXUS_EMBEDDING_THREADS) is present but Number(value) is not an integer or is <= 0. The embedding pipeline needs positive integer batch/thread counts to size ONNX sessions and chunk Cypher writes; a zero/negative/fractional value would produce empty batches or undefined threading. Unlike the vector-distance parser (which warns-and-clamps), integer config is strict because there is no safe clamp.

Source

Thrown at gitnexus/src/core/embeddings/config.ts:55

      `  GITNEXUS_VECTOR_MAX_DISTANCE must be a positive number in (0, ${VECTOR_MAX_DISTANCE_CEILING}], got "${raw}" — using default ${fallback}`,
    );
    return fallback;
  }
  if (parsed > VECTOR_MAX_DISTANCE_CEILING) {
    warnOnce(
      `clamp:${raw}`,
      `  GITNEXUS_VECTOR_MAX_DISTANCE=${parsed} exceeds the cosine-distance ceiling (${VECTOR_MAX_DISTANCE_CEILING}) — clamping`,
    );
    return VECTOR_MAX_DISTANCE_CEILING;
  }
  return parsed;
};

const parsePositiveInt = (name: string, value: string | undefined, fallback: number): number => {
  if (value === undefined) return fallback;
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    throw new Error(`${name} must be a positive integer, got "${value}"`);
  }
  return parsed;
};

const parseDevice = (value: string | undefined): EmbeddingConfig['device'] | undefined => {
  if (value === undefined) return undefined;
  if (
    value === 'auto' ||
    value === 'dml' ||
    value === 'cuda' ||
    value === 'cpu' ||
    value === 'wasm'
  ) {
    return value;
  }
  throw new Error(`embedding device must be one of auto, dml, cuda, cpu, wasm; got "${value}"`);
};

View on GitHub (pinned to d540b00184)

Solutions

  1. Set the named env var to a positive whole number, e.g. GITNEXUS_EMBEDDING_BATCH_SIZE=32.
  2. Unset the variable to accept the built-in default (batchSize/subBatchSize from DEFAULT_EMBEDDING_CONFIG, threads from defaultEmbeddingThreads()).
  3. For thread count, leave it unset rather than 0 — auto-detection only runs when the var is undefined.

Example fix

// before
export GITNEXUS_EMBEDDING_THREADS=0
// after — omit for auto, or set a real positive integer
unset GITNEXUS_EMBEDDING_THREADS
# or
export GITNEXUS_EMBEDDING_THREADS=4
Defensive patterns

Strategy: validation

Validate before calling

// Validate embedding integer env vars before resolving config.
const assertPositiveIntEnv = (name: string): void => {
  const v = process.env[name];
  if (v === undefined) return;
  const n = Number(v);
  if (!Number.isInteger(n) || n <= 0) {
    throw new Error(`${name} must be a positive integer; unset it or use a whole number > 0.`);
  }
};
['GITNEXUS_EMBEDDING_BATCH_SIZE', 'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE', 'GITNEXUS_EMBEDDING_THREADS']
  .forEach(assertPositiveIntEnv);

Type guard

const isPositiveInt = (v: string | undefined): boolean =>
  v === undefined || (Number.isInteger(Number(v)) && Number(v) > 0);

Try / catch

try {
  resolveEmbeddingConfig();
} catch (err) {
  if (err instanceof Error && /must be a positive integer/.test(err.message)) {
    console.error('Bad embedding config:', err.message, '— unsetting and retrying with defaults.');
    delete process.env.GITNEXUS_EMBEDDING_BATCH_SIZE; // etc.
  }
  throw err;
}

Prevention

When it happens

Trigger: resolveEmbeddingConfig() calls parsePositiveInt for the three env vars at config.ts:81-95. Fires on e.g. GITNEXUS_EMBEDDING_BATCH_SIZE=0, =2.5, =-1, =abc, or an empty-ish non-undefined value. The analyze command and the MCP embedder both resolve config before model load.

Common situations: Setting GITNEXUS_EMBEDDING_THREADS=0 thinking it means auto (it does not — auto is the unset default); copy-pasting a float batch size from docs; a shell script exporting a computed value that evaluated to empty or 0; setting a value with a unit suffix like 4x.

Related errors

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