apple/pkl · error

integerOverflow

integerOverflow

Error message

integerOverflow

What it means

Thrown when subtracting two Pkl `Int` values overflows 64-bit signed range (StrictMath.subtractExact throws ArithmeticException). Pkl integers are fixed-size Longs, so results below Long.MIN_VALUE are rejected instead of silently wrapping.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/binary/SubtractionNode.java:36

import com.oracle.truffle.api.CompilerDirectives;
import com.oracle.truffle.api.dsl.Specialization;
import com.oracle.truffle.api.nodes.NodeInfo;
import com.oracle.truffle.api.source.SourceSection;
import org.pkl.core.runtime.*;

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

  @Specialization
  protected long eval(long left, long right) {
    try {
      return StrictMath.subtractExact(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. Perform the subtraction as `Float`/`Double` if exact integer precision is not required
2. Split the computation so intermediate values stay in range
3. Use `Int` values that fit in the 64-bit range; validate magnitudes before subtracting
4. Consider `IntSeq`/string-based big values or restructure to avoid extremes

Example fix

// before
result = bigInt - otherBigInt
// after
result = bigInt.toDouble() - otherBigInt

function canSubtract(a, b) { return (a - b) >= -9223372036854775808n }

function inInt64Range(x) { return x >= -9223372036854775808n && x <= 9223372036854775807n }

When it happens

Trigger: Evaluating `left - right` where the mathematical result is less than -9223372036854775808; e.g. subtracting a large positive from Long.MIN_VALUE, or accumulating large differences in a loop.

Common situations: Big-number arithmetic on config values (byte offsets, timestamps in nanoseconds), porting code that assumed arbitrary-precision or wrapped arithmetic.

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