apple/pkl · error · VmException

intValueTooLarge

intValueTooLarge

Error message

intValueTooLarge

What it means

`VmSafeMath.toInt32` converts a 64-bit long to a 32-bit int via `StrictMath.toIntExact`, which throws ArithmeticException when the value does not fit in Int32 range (-2147483648..2147483647). The runtime re-raises it as an evalError with the offending value.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/VmSafeMath.java:105

    }

    return result;
  }

  public static long remainder(long x, long y) {
    return x % y;
  }

  public static double remainder(double x, double y) {
    return x % y;
  }

  public static int toInt32(long x) {
    try {
      return StrictMath.toIntExact(x);
    } catch (ArithmeticException e) {
      CompilerDirectives.transferToInterpreter();
      throw new VmExceptionBuilder().evalError("intValueTooLarge", x).build();
    }
  }

  public static double truncate(double x) {
    if (x < 0) {
      return StrictMath.ceil(x);
    }
    return StrictMath.floor(x);
  }

  @TruffleBoundary
  public static long toInt(double x, Node sourceNode) {
    try {
      return MathUtils.roundToLong(x, RoundingMode.DOWN);
    } catch (ArithmeticException e) {
      CompilerDirectives.transferToInterpreter();
      throw new VmExceptionBuilder()
          .withLocation(sourceNode)

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Check the value is within -2147483648..2147483647 before converting.
  2. Keep the value as a Pkl Int (64-bit) if full range is needed.
  3. Pre-clip with explicit bounds: `if (x > 2147483647) ... else x.toInt32()`.
  4. Recompute the expression in a way that cannot overflow (e.g. divide or mask before converting).

Example fix

// before
val flags = hugeCounter.toInt32()
// after
val flags = (hugeCounter % 2147483648).toInt32()
Defensive patterns

Strategy: validation

Validate before calling

function fitsInt32(x) { return x >= -2147483648 && x <= 2147483647; }

Type guard

function isInt32Safe(x) { return typeof x === 'number' && Number.isInteger(x) && x >= -2147483648 && x <= 2147483647; }

Try / catch

try { x.toInt32() } catch (e) { /* value out of Int32 range; fall back to 64-bit Int */ }

Prevention

When it happens

Trigger: Any Pkl Int-to-Int32 conversion where the long operand is outside the Int32 range, e.g. `x.toInt32()` on a large Int, or Int32-returning stdlib functions given out-of-range arguments.

Common situations: Bit-manipulation code (` shl `, `and`, masks) on big integers; passing computed values like timestamps in milliseconds beyond Int32 bounds to Int32 APIs.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/05c7939361d486d7. Report an issue: GitHub.