GITNEXUS_MAX_FILE_SIZE must be a positive integer (KB), go

Error message

  GITNEXUS_MAX_FILE_SIZE must be a positive integer (KB), got "${raw}" — using default ${DEFAULT_MAX_FILE_SIZE_BYTES / 1024}KB

What it means

getMaxFileSizeBytes() reads GITNEXUS_MAX_FILE_SIZE (in KB) for the walker's file-size skip threshold. A value that is not a finite positive integer (0, negatives, floats like 1.5, or strings like 10MB) is rejected: the default 512KB threshold is used instead and a one-time warning is emitted via warnOnce keyed by the raw value.

Source

Thrown at gitnexus/src/core/ingestion/utils/max-file-size.ts:31

  if (warned.has(key)) return;
  warned.add(key);
  logger.warn(message);
};

/**
 * Resolve the effective file-size skip threshold (bytes) for the walker.
 * Reads `GITNEXUS_MAX_FILE_SIZE` (KB). Invalid values fall back to the default
 * and emit a one-time warning. Values above the tree-sitter ceiling are clamped.
 */
export const getMaxFileSizeBytes = (): number => {
  const raw = process.env.GITNEXUS_MAX_FILE_SIZE;
  if (!raw) return DEFAULT_MAX_FILE_SIZE_BYTES;

  const parsed = Number(raw);
  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
    warnOnce(
      `invalid:${raw}`,
      `  GITNEXUS_MAX_FILE_SIZE must be a positive integer (KB), got "${raw}" — using default ${DEFAULT_MAX_FILE_SIZE_BYTES / 1024}KB`,
    );
    return DEFAULT_MAX_FILE_SIZE_BYTES;
  }

  const bytes = parsed * 1024;
  if (bytes > MAX_FILE_SIZE_UPPER_BOUND_BYTES) {
    warnOnce(
      `clamp:${raw}`,
      `  GITNEXUS_MAX_FILE_SIZE=${parsed}KB exceeds tree-sitter ceiling (${MAX_FILE_SIZE_UPPER_BOUND_BYTES / 1024}KB) — clamping`,
    );
    return MAX_FILE_SIZE_UPPER_BOUND_BYTES;
  }
  return bytes;
};

/**
 * Build the CLI banner message announcing an active file-size override.
 * Returns `null` when the effective threshold equals the default — the caller

View on GitHub (pinned to aac7515d2a)

Solutions

Set a positive integer in KB, e.g. GITNEXUS_MAX_FILE_SIZE=2048 for 2MB
If you intended 'no limit', remember values above the tree-sitter ceiling are clamped, not honored — check the clamp warning instead
Confirm the banner printed at startup reflects the effective threshold you expect
Unset the variable if the default 512KB is acceptable and you only wanted the noise gone

Example fix

# before
export GITNEXUS_MAX_FILE_SIZE=10MB   # invalid → warn, effective 512KB
# after
export GITNEXUS_MAX_FILE_SIZE=10240   # 10MB in KB, honored

Defensive patterns

Strategy: validation

Validate before calling

// Validate before the walk starts:
const raw = process.env.GITNEXUS_MAX_FILE_SIZE;
if (raw !== undefined && !/^\d+$/.test(raw)) {
  throw new Error(`GITNEXUS_MAX_FILE_SIZE must be an integer KB count, got: ${raw}`);
}

Type guard

function isKbInteger(raw: string | undefined): raw is string {
  return raw !== undefined && /^\d+$/.test(raw) && Number(raw) > 0;
}

Prevention

Always express the value as integer KB (2048, not 2MB / 2.0 / 2048KB)
Assert the startup banner's effective threshold matches your intent before large runs
Prefer unset (512KB default) over guessed values when unsure

When it happens

Trigger: Starting any indexing walk with GITNEXUS_MAX_FILE_SIZE set to a non-integer, non-positive, or non-numeric value; the first call to getMaxFileSizeBytes() triggers warnOnce and every later call silently uses DEFAULT_MAX_FILE_SIZE_BYTES (512 * 1024).

Common situations: Operators copying a size like 10MB or 1.5GB into the env var (unit suffixes are unsupported — the value is KB only), exporting 0 expecting 'no limit', stale dotfiles carrying a float, or shell-quoting mistakes.

Related errors

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