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.

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)

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 `%s` to java.lang.Byte because i

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