What causes "${name} must be >= ${min} && <= ${max}. Value was ${value}" in denoland/deno?

Cap or chunk the operation so each call stays within int32 range (read huge files in segments)

denoland/deno · error · Error

${name} must be >= ${min} && <= ${max}. Value was ${value}

Error message

${name} must be >= ${min} && <= ${max}. Value was ${value}

What it means

The range half of validateIntegerRange (ext/node/polyfills/_utils.ts:117): the value is an integer but falls outside [min, max] (defaults to int32 bounds -2147483648..2147483647). Throws a plain Error '<name> must be >= <min> && <= <max>. Value was <value>'. Typical victims are lengths, positions, and sizes that exceed 2^31-1 when the API is backed by a 32-bit field.

Source

Thrown at ext/node/polyfills/_utils.ts:117

  for (; index + 1 < list.length; index++) {
    list[index] = list[index + 1];
  }
  ArrayPrototypePop(list);
}

function validateIntegerRange(
  value: number,
  name: string,
  min = -2147483648,
  max = 2147483647,
) {
  // The defaults for min and max correspond to the limits of 32-bit integers.
  if (!NumberIsInteger(value)) {
    throw new Error(`${name} must be 'an integer' but was ${value}`);
  }

  if (value < min || value > max) {
    throw new Error(
      `${name} must be >= ${min} && <= ${max}. Value was ${value}`,
    );
  }
}

type OptionalSpread<T> = T extends undefined ? []
  : [T];

function once<T = undefined>(
  callback: (...args: OptionalSpread<T>) => void,
) {
  let called = false;
  return function (this: unknown, ...args: OptionalSpread<T>) {
    if (called) return;
    called = true;
    FunctionPrototypeApply(callback, this, args);
  };
}

View on GitHub (pinned to 89f33cbef2)

Solutions

Cap or chunk the operation so each call stays within int32 range (read huge files in segments)
Validate before the call: if (!(n >= 0 && n <= 0x7fffffff)) throw new RangeError(...) with your own message
Check whether the same result is available from an API taking Number/BigInt sized arguments

Example fix

// before
fs.readSync(fd, buf, 0, 3 * 1024 ** 3, 0); // > int32 max

// after
const CHUNK = 1 << 30;
for (let off = 0; off < size; off += CHUNK) {
  fs.readSync(fd, buf, 0, Math.min(CHUNK, size - off), off);
}

Defensive patterns

Strategy: validation

Validate before calling

const MAX = 2147483647; if (!(Number.isInteger(n) && n >= 0 && n <= MAX)) throw new RangeError(`${name} out of int32 range`);

Type guard

function isInt32(n) { return Number.isInteger(n) && n >= -2147483648 && n <= 2147483647; }

Try / catch

try { api(n); } catch (e) { if (/must be >=/.test(e.message)) { /* chunk the operation */ } else throw e; }

Prevention

Chunk large reads/writes so each length/position stays under 2^31-1
Validate computed byte sizes against int32 bounds at the boundary

When it happens

Trigger: Passing 3e9 as a byte length or start position (exceeds int32 max); negative values where min is 0; reading a huge file with an offset larger than 2147483647 (files over 2 GiB).

Common situations: Large-file handling (>2 GiB) on APIs that take 32-bit positions; sizes computed in bytes from GB-scale products (e.g. 3 * 1024**3); port-like values passed to size arguments by argument mix-ups.

Related errors

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/919460f4e1478bbe. Report an issue: GitHub.