abhigyanpatwari/GitNexus · error · Error

must be a positive integer <= , got

Error message

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

What it means

parsePositiveIntegerEnv() second guard: the value is all digits but Number(raw) is not a safe positive integer within the variable's cap (GITNEXUS_EMBEDDING_MAX_ATTEMPTS ≤ 20; GITNEXUS_EMBEDDING_RETRY_CAP_MS ≤ 300000; GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS ≤ 300000). '0' hits this too — zero is not positive.

Solutions

  1. Lower the value to the maximum stated in the message (e.g. timeout ≤ 300000 ms).
  2. Use a value ≥ 1; to get default behavior unset the variable entirely.
  3. Double-check units — these knobs are milliseconds, not seconds, and attempts, not retries.

Example fix

# before
export GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS=600000   # 10min > 300000 cap
# after
export GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS=300000
Defensive patterns

Strategy: validation

Validate before calling

const LIMITS: Record<string, number> = {
  GITNEXUS_EMBEDDING_MAX_ATTEMPTS: 20,
  GITNEXUS_EMBEDDING_RETRY_CAP_MS: 300_000,
  GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS: 300_000,
};
for (const [name, max] of Object.entries(LIMITS)) {
  const v = Number(process.env[name]);
  if (process.env[name] && (!Number.isSafeInteger(v) || v <= 0 || v > max)) {
    throw new Error(`${name} must be 1..${max}`);
  }
}

Type guard

const isEnvRangeError = (e: unknown): boolean =>
  e instanceof Error && /must be a positive integer <=/.test(e.message);

Try / catch

try {
  await httpEmbed(texts);
} catch (e) {
  if (isEnvRangeError(e)) { /* fix the value cited in the message; non-retryable */ }
  else throw e;
}

Prevention

When it happens

Trigger: GITNEXUS_EMBEDDING_MAX_ATTEMPTS=0 or 21+, GITNEXUS_EMBEDDING_RETRY_CAP_MS=999999, GITNEXUS_EMBEDDING_HTTP_TIMEOUT_MS=600000, or absurd values like '99999999999999999999' that exceed Number.MAX_SAFE_INTEGER.

Common situations: Users pasting millisecond values in seconds ('180000' vs intended '180'), setting MAX_ATTEMPTS=0 to 'disable retries' (not supported — unset it instead), or copying a cap-busting timeout from another tool's config.

Related errors

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

Appendix: source

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

  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 ac9a4e9abd)