abhigyanpatwari/GitNexus · error · Error

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

Error message

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

What it means

Thrown by parsePositiveIntegerEnv() in http-client.ts when the value passes the digits-only regex but Number(raw) is not a safe integer, is <= 0, or exceeds the per-variable max. Each variable has its own ceiling: GITNEXUS_EMBEDDING_MAX_ATTEMPTS ≤ 20, GITNEXUS_EMBEDDING_RETRY_CAP_MS ≤ 300000, GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS ≤ MAX_HTTP_TIMEOUT_MS (300000). The ceiling prevents runaway retry/timeout configs that would hang the embedding pipeline.

Source

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

  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}"`);
  }
  return parsed;
};

const cancelledError = (): DOMException =>

View on GitHub (pinned to d540b00184)

Solutions

  1. Set the variable within its documented ceiling (max attempts ≤ 20, retry cap ≤ 300000ms, timeout ≤ 300000ms).
  2. Set GITNEXUS_EMBEDDING_MAX_ATTEMPTS=1 to disable retries rather than 0.
  3. Unset the variable to accept the default, which is already within bounds.

Example fix

# before
export GITNEXUS_EMBEDDING_MAX_ATTEMPTS=100
# after
export GITNEXUS_EMBEDDING_MAX_ATTEMPTS=20  # the ceiling
Defensive patterns

Strategy: validation

Validate before calling

const CEILINGS = {
  GITNEXUS_EMBEDDING_MAX_ATTEMPTS: 20,
  GITNEXUS_EMBEDDING_RETRY_CAP_MS: 300_000,
  GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS: 300_000,
} as const;
for (const [name, max] of Object.entries(CEILINGS)) {
  const v = process.env[name];
  if (v === undefined) continue;
  const n = Number(v);
  if (!Number.isSafeInteger(n) || n <= 0 || n > max) {
    throw new Error(`${name} must be a positive integer <= ${max}; got \"${v}\"`);
  }
}

Type guard

const isWithinPositiveCeiling = (v: string, max: number): boolean => {
  const n = Number(v);
  return Number.isSafeInteger(n) && n > 0 && n <= max;
};

Prevention

When it happens

Trigger: readConfig() at http-client.ts:189-204. Fires on e.g. GITNEXUS_EMBEDDING_MAX_ATTEMPTS=0, =999, GITNEXUS_EMBEDDING_RETRY_CAP_MS=1000000, GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS=9999999. A value exceeding Number.MAX_SAFE_INTEGER would also fail the Number.isSafeInteger guard.

Common situations: Setting a very large retry cap or timeout thinking higher is safer; setting attempts to 0 to disable retries (use 1 instead); a computed value that overflowed into an unsafe integer.

Related errors

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