GITNEXUS_MAX_FILE_SIZE=${parsed}KB exceeds tree-sitter cei

Error message

  GITNEXUS_MAX_FILE_SIZE=${parsed}KB exceeds tree-sitter ceiling (${MAX_FILE_SIZE_UPPER_BOUND_BYTES / 1024}KB) — clamping

What it means

A valid GITNEXUS_MAX_FILE_SIZE (positive integer KB) whose byte value exceeds the tree-sitter parser buffer ceiling (MAX_FILE_SIZE_UPPER_BOUND_BYTES = TREE_SITTER_MAX_BUFFER) is clamped down to that ceiling with a one-time warnOnce. The effective threshold the walker uses is always the post-clamp value, which the CLI banner also reflects.

Source

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

 */
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
 * should print nothing in that case. The returned message reflects the
 * *effective* post-clamp threshold, not the raw env value, so operators reading
 * startup output see the actual configuration the walker will use.
 */
export const getMaxFileSizeBannerMessage = (): string | null => {
  const effectiveBytes = getMaxFileSizeBytes();
  if (effectiveBytes === DEFAULT_MAX_FILE_SIZE_BYTES) return null;
  const effectiveKb = effectiveBytes / 1024;
  const defaultKb = DEFAULT_MAX_FILE_SIZE_BYTES / 1024;

View on GitHub (pinned to aac7515d2a)

Solutions

Keep the value at or below the tree-sitter ceiling shown in the message; larger inputs cannot be parsed anyway
Split or exclude the oversized artifacts (vendored bundles, lockfile-scale JSON, generated data) from indexing instead of raising the limit
Read the startup banner to verify the effective post-clamp threshold matches what you planned
If you genuinely need huge files parsed, reduce the files' size at the source — no env can raise the native ceiling

Example fix

# before
export GITNEXUS_MAX_FILE_SIZE=1048576   # 1GB → exceeds ceiling, clamped with warn
# after
export GITNEXUS_MAX_FILE_SIZE=8192      # 8MB, under ceiling, no clamp

Defensive patterns

Strategy: validation

Validate before calling

// Pre-clamp yourself so the effective value is explicit:
const TREE_SITTER_CEILING_KB = 64 * 1024; // keep in sync with the ceiling in the warn
const wanted = Number(process.env.GITNEXUS_MAX_FILE_SIZE ?? 512);
process.env.GITNEXUS_MAX_FILE_SIZE = String(Math.min(wanted, TREE_SITTER_CEILING_KB));

Prevention

Never try to disable the size limit via a huge value — the native buffer ceiling wins
Exclude oversized generated artifacts from indexing instead of raising the cap past the ceiling
Read the banner: it shows the post-clamp effective threshold, which is what the walker uses

When it happens

Trigger: Setting GITNEXUS_MAX_FILE_SIZE to a KB value whose parsed * 1024 bytes exceeds the tree-sitter max buffer (e.g. hundreds of MB trying to 'index everything'); getMaxFileSizeBytes() returns the ceiling instead.

Common situations: Operators attempting to disable the size skip by entering a huge number; repos containing minified bundles or generated data files larger than the parser ceiling, where the assumption is that raising the limit enough will index them — it cannot beyond the native buffer size.

Related errors

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