apple/pkl · error · VmTypeMismatchException

type constraint violation: value does not fit in Int32

Error message

type constraint violation: value does not fit in Int32

What it means

The Int32 variant: a Long is valid for the Int32 alias only if l == l.intValue() (fits signed 32-bit). Otherwise the constraint exception is thrown at the Int32 alias's constraint section; non-Long values raise a VmTypeMismatchException.Simple against Int.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java:2701

    @Override
    protected boolean acceptTypeNode(boolean visitTypeArguments, TypeNodeConsumer consumer) {
      return consumer.accept(this);
    }
  }

  public static final class Int32TypeAliasTypeNode extends IntSlotTypeNode {
    public Int32TypeAliasTypeNode() {
      super(VmUtils.unavailableSourceSection());
    }

    @Override
    protected Object executeLazily(VirtualFrame frame, Object value) {
      if (value instanceof Long l) {
        if (l == l.intValue()) return value;

        CompilerDirectives.transferToInterpreterAndInvalidate();
        throw constraintException(value, BaseModule.getInt32TypeAlias().getConstraintSection());
      }

      CompilerDirectives.transferToInterpreterAndInvalidate();
      throw new VmTypeMismatchException.Simple(
          BaseModule.getInt32TypeAlias().getBaseTypeSection(), value, BaseModule.getIntClass());
    }

    @Override
    public VmClass getVmClass() {
      return BaseModule.getIntClass();
    }

    @Override
    public VmTypeAlias getVmTypeAlias() {
      return BaseModule.getInt32TypeAlias();
    }

    @Override

View on GitHub (pinned to f3efcbfc9b)

Solutions

Declare the property as Int (Pkl's unbounded machine integer) instead of Int32
Split the computation so intermediate values stay in 32-bit range
Fix a wrong (non-integer) value at the source
Use `v is Int32` to validate before assignment

Example fix

// before
durationNs: Int32 = 5_000_000_000
// after
durationNs: Int = 5_000_000_000

Defensive patterns

Strategy: validation

Validate before calling

function fitsInt32(v) { return Number.isInteger(v) && v >= -2147483648 && v <= 2147483647; }

Type guard

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

Prevention

Use Int for timestamps, byte counts, and nanosecond math
Audit arithmetic that can overflow 32 bits (seconds*1e9 etc.)

When it happens

Trigger: Assigning a value outside -2147483648..2147483647 to an Int32-typed property (e.g. nanosecond timestamps, byte counts > 2 GiB), or a Float/String reaching the check.

Common situations: Timestamps or file sizes stored as Int32; arithmetic overflow like `seconds * 1_000_000_000`; deserialized large numbers from JSON imports.

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