abhigyanpatwari/GitNexus · error · Error

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

Error message

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

What it means

Thrown by parsePositiveIntegerEnv() in http-client.ts when an HTTP-mode embedding env var it owns (GITNEXUS_EMBEDDING_MAX_ATTEMPTS, GITNEXUS_EMBEDDING_RETRY_CAP_MS, GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS) is set to a value that fails the /^\d+$/u regex — i.e. contains any non-digit character. The regex-level check fires before the numeric range check (error 116), catching negatives (-1 has a leading -), decimals (1.5), and junk (abc) with a clear 'must be a positive integer' message naming the offending variable.

Source

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

  maxAttempts: number;
  retryCapMs: number;
  minIntervalMs: number;
  timeoutMs: number;
  requestDimensions?: number;
}

export interface EmbeddingRequestOptions {
  signal?: AbortSignal;
}

let lastHttpRequestStartedAt: number | undefined;
let httpPaceQueue: Promise<void> = Promise.resolve();

const parsePositiveIntegerEnv = (name: string, fallback: number, max: number): number => {
  const raw = process.env[name];
  if (raw === undefined || raw === '') return fallback;
  if (!/^\d+$/u.test(raw)) {
    throw new Error(`${name} must be a positive integer, got "${raw}"`);
  }
  const parsed = Number(raw);
  if (!Number.isSafeInteger(parsed) || parsed <= 0 || parsed > max) {
    throw new Error(`${name} must be a positive integer <= ${max}, got "${raw}"`);
  }
  return parsed;
};

const parseNonNegativeIntegerEnv = (name: string, fallback: number, max: number): number => {
  const raw = process.env[name];
  if (raw === undefined || raw === '') return fallback;
  if (!/^\d+$/u.test(raw)) {
    throw new Error(`${name} must be a non-negative integer, got "${raw}"`);
  }
  const parsed = Number(raw);
  if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > max) {
    throw new Error(`${name} must be a non-negative integer <= ${max}, got "${raw}"`);
  }

View on GitHub (pinned to d540b00184)

Solutions

  1. Set the named env var to a plain positive integer string of digits only.
  2. Unset it to accept the documented default (attempts 3, retry cap 5000ms, timeout 180000ms).
  3. If you wanted unlimited attempts, use a large finite value within the per-variable max instead of a negative.

Example fix

# before
export GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS=300s
# after
export GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS=300000
Defensive patterns

Strategy: validation

Validate before calling

const assertDigitsOnly = (name: string): void => {
  const v = process.env[name];
  if (v !== undefined && v !== '' && !/^\d+$/u.test(v)) {
    throw new Error(`${name} must be a positive-integer string of digits only; got \"${v}\"`);
  }
};
['GITNEXUS_EMBEDDING_MAX_ATTEMPTS', 'GITNEXUS_EMBEDDING_RETRY_CAP_MS', 'GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS']
  .forEach(assertDigitsOnly);

Type guard

const isDigitsOnly = (v: string | undefined): boolean =>
  v === undefined || v === '' || /^\d+$/u.test(v);

Prevention

When it happens

Trigger: readConfig() calls parsePositiveIntegerEnv for the three HTTP tuning vars at http-client.ts:189-204. Fires only when GITNEXUS_EMBEDDING_URL and GITNEXUS_EMBEDDING_MODEL are both set (readConfig returns null otherwise). Examples: GITNEXUS_EMBEDDING_MAX_ATTEMPTS=-1, =1.5, =3x, =abc.

Common situations: Using a negative value to mean 'unlimited' (not supported — use the max cap); a unit suffix from copy-paste (300s, 5x); a float timeout from a computed config; a YAML that coerced the value to a string with surrounding quotes/whitespace.

Related errors

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