apple/pkl · error

integerOverflow

integerOverflow

Error message

integerOverflow

What it means

Thrown when truncating integer division produces the one result that overflows 64-bit range: `Long.MIN_VALUE ~/ -1` (mathematically +2^63, which exceeds Long.MAX_VALUE). The `(left & right & result) < 0` bit trick detects exactly this case.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/binary/TruncatingDivisionNode.java:48

public abstract class TruncatingDivisionNode extends BinaryExpressionNode {
  protected TruncatingDivisionNode(SourceSection sourceSection) {
    super(sourceSection);
  }

  @Specialization
  protected long eval(long left, long right) {
    if (right == 0) {
      CompilerDirectives.transferToInterpreter();
      throw exceptionBuilder().evalError("divisionByZero").build();
    }

    var result = left / right;

    // use same check as com.oracle.truffle.sl.nodes.expression.SLDivNode
    if ((left & right & result) < 0) {
      CompilerDirectives.transferToInterpreter();
      assert left == Long.MIN_VALUE && right == -1;
      throw exceptionBuilder().evalError("integerOverflow").build();
    }
    return result;
  }

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

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

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

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Convert to `Double`/`Float` before dividing when operands may be extreme
2. Check for `left == Int.MIN_VALUE && right == -1` beforehand and handle specially
3. Clamp or validate operand ranges so Long.MIN_VALUE paired with -1 never reaches the operator

Example fix

// before
result = minInt ~/ -1
// after
result = (minInt.toDouble() / -1).truncate()

function canTruncDiv(a, b) { return !(a === -9223372036854775808n && b === -1n) }

function isSafeDividend(a) { return a > -9223372036854775808n }

When it happens

Trigger: Evaluating `left ~/ right` where `left == Long.MIN_VALUE (-9223372036854775808)` and `right == -1`.

Common situations: Dividing extreme sentinel values, negating/normalizing Long.MIN_VALUE in scaling or percentage computations.

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/ead92175fb322c2c. Report an issue: GitHub.