apple/pkl · error

integerOverflow

integerOverflow

Error message

integerOverflow

What it means

Pkl's `+` operator on two Ints uses StrictMath.addExact and throws `integerOverflow` when the mathematical sum exceeds the 64-bit signed Long range. Pkl integers are fixed-width longs, so silent wraparound is never allowed. The error surfaces at the site of the addition expression in Pkl source.

Solutions

1. Reduce operand magnitudes or restructure the computation so intermediate sums stay within Long range
2. Convert one operand to Float (`left.toDouble() + right`) if approximate precision is acceptable
3. Use pkl-math or break the sum into checked stages if exact big values are required

Example fix

// before (Pkl)
val total = 9223372036854775807 + 1
// after
val total = 9223372036854775807.0 + 1.0 // Float arithmetic, no overflow

function canAddSafely(a, b) {
  return a <= Number.MAX_SAFE_INTEGER && b <= Number.MAX_SAFE_INTEGER &&
         (b > 0 ? a <= Number.MAX_SAFE_INTEGER - b : true);
}

const isPklInt = (v) => typeof v === 'number' && Number.isInteger(v) && v >= -(2**63) && v <= 2**63 - 1;

When it happens

Trigger: Evaluating `left + right` where both operands are Int and the result is > Long.MAX_VALUE (9223372036854775807) or < Long.MIN_VALUE, e.g. `9223372036854775807 + 1`.

Common situations: Accumulating large counters, byte/duration arithmetic in raw integer form, or summing user-supplied config numbers that individually fit but together overflow.

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

• integerOverflow
• integerOverflow
• integerOverflow
• integerOverflow
• Cannot convert pkl.base#Int

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/binary/AdditionNode.java:43

@NodeInfo(shortName = "+")
public abstract class AdditionNode extends BinaryExpressionNode {
  protected AdditionNode(SourceSection sourceSection) {
    super(sourceSection);
  }

  @Specialization
  @TruffleBoundary
  protected String eval(String left, String right) {
    return left + right;
  }

  @Specialization
  protected long eval(long left, long right) {
    try {
      return StrictMath.addExact(left, right);
    } catch (ArithmeticException e) {
      CompilerDirectives.transferToInterpreter();
      throw exceptionBuilder().evalError("integerOverflow").build();
    }
  }

  @Specialization
  protected double eval(long left, double right) {
    return left + right;
  }

  @Specialization
  protected double eval(double left, long right) {
    return left + right;
  }

  @Specialization
  protected double eval(double left, double right) {
    return left + right;
  }

View on GitHub (pinned to f3efcbfc9b)