abhigyanpatwari/GitNexus · error · Error

GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${r

Error message

GITNEXUS_EMBEDDING_DIMS must be a positive integer, got "${rawDims}"

What it means

Thrown by readConfig() in http-client.ts when GITNEXUS_EMBEDDING_DIMS is set but is not a string of digits, or parses to a non-positive integer. GITNEXUS_EMBEDDING_DIMS declares the vector dimensionality of the HTTP endpoint's model so the local index can be sized correctly; a malformed value would create a dimension mismatch at query time. The error lead is generated by dimsEnvErrorLead('GITNEXUS_EMBEDDING_DIMS') so the CLI's isHttpEmbeddingDimsError() can recognize it and print a clean config message instead of a stack dump (#2385).

Source

Thrown at gitnexus/src/core/embeddings/http-client.ts:158

/**
 * Build config from the current process.env snapshot.
 * Returns null when GITNEXUS_EMBEDDING_URL + GITNEXUS_EMBEDDING_MODEL are unset.
 * Not cached — env vars are read fresh so late configuration takes effect.
 * Validates GITNEXUS_EMBEDDING_DIMS and throws on a malformed value; callers
 * that only need to know whether HTTP mode is *configured* must use
 * {@link isHttpMode} (a presence probe that never throws), not this.
 */
const readConfig = (): HttpConfig | null => {
  const baseUrl = process.env.GITNEXUS_EMBEDDING_URL;
  const model = process.env.GITNEXUS_EMBEDDING_MODEL;
  if (!baseUrl || !model) return null;

  const rawDims = process.env.GITNEXUS_EMBEDDING_DIMS;
  let dimensions: number | undefined;
  if (rawDims !== undefined) {
    if (!/^\d+$/.test(rawDims)) {
      throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got "${rawDims}"`);
    }
    const parsed = parseInt(rawDims, 10);
    if (parsed <= 0) {
      throw new Error(`${EMBEDDING_DIMS_ENV_ERROR_LEAD}, got "${rawDims}"`);
    }
    dimensions = parsed;
  }

  const rawRequestDims = process.env.GITNEXUS_EMBEDDING_REQUEST_DIMS?.trim();
  let requestDimensions = dimensions;
  if (rawRequestDims) {
    if (/^(omit|none|off|false|0)$/i.test(rawRequestDims)) {
      requestDimensions = undefined;
    } else {
      if (!/^\d+$/.test(rawRequestDims)) {
        throw new Error(`${EMBEDDING_REQUEST_DIMS_ENV_ERROR_LEAD}, got "${rawRequestDims}"`);
      }
      const parsed = parseInt(rawRequestDims, 10);

View on GitHub (pinned to d540b00184)

Solutions

  1. Set GITNEXUS_EMBEDDING_DIMS to a positive integer matching your model's vector size, e.g. 1536 for text-embedding-3-small.
  2. Unset it to fall back to DEFAULT_DIMS (384) — only correct if your model happens to be 384-dim.
  3. Verify the value against the endpoint's documentation before retrying.

Example fix

# before
export GITNEXUS_EMBEDDING_DIMS=1536d
# after
export GITNEXUS_EMBEDDING_DIMS=1536
Defensive patterns

Strategy: validation

Validate before calling

const v = process.env.GITNEXUS_EMBEDDING_DIMS;
if (v !== undefined) {
  if (!/^\d+$/.test(v) || parseInt(v, 10) <= 0) {
    throw new Error('GITNEXUS_EMBEDDING_DIMS must be a positive integer matching the model vector size.');
  }
}

Type guard

const isValidDims = (v: string | undefined): boolean =>
  v === undefined || (/^\d+$/.test(v) && parseInt(v, 10) > 0);

Try / catch

import { isHttpEmbeddingDimsError } from 'gitnexus/src/core/embeddings/http-client.js';
try {
  // any operation that triggers readConfig(), e.g. isHttpMode-then-httpEmbed
  await embedText(text);
} catch (err) {
  const msg = err instanceof Error ? err.message : String(err);
  if (isHttpEmbeddingDimsError(msg)) {
    console.error('Fix GITNEXUS_EMBEDDING_DIMS to a positive integer and retry.');
    process.exit(1);
  }
  throw err;
}

Prevention

When it happens

Trigger: readConfig() at http-client.ts:154-165, invoked whenever HTTP mode is active (both GITNEXUS_EMBEDDING_URL and GITNEXUS_EMBEDDING_MODEL set). Fires on e.g. GITNEXUS_EMBEDDING_DIMS=384d, =-1, =1.5, =auto, =0. Note: getHttpDimensions() also calls readConfig(), so merely reading dimensions surfaces this.

Common situations: Adding a unit suffix (384d, 1536-d); a negative or zero from a miscomputed config; a non-numeric placeholder (auto) copy-pasted from a model card; setting dims that don't match the endpoint model (this error only catches malformed strings, not wrong-but-valid dims).

Related errors

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