apple/pkl · error · VmTypeMismatchException.Simple

VmTypeMismatchException.Simple (value is not an Int32 in…

Error message

VmTypeMismatchException.Simple (value is not an Int32 in range)

What it means

Int32TypeAliasTypeNode checks the `Int32` typealias: the value must be an Int within -2147483648..2147483647. Values that pass the base Int check but fail the range constraint raise the typealias's constraint exception; values that are not in-range Int32s at all raise VmTypeMismatchException.Simple with the base type section (vmClass Int).

Solutions

Use a value within the 32-bit range, or switch the annotation to `Int`.
Convert string inputs with `.toInt()` before assignment.
If 32-bit width is required (e.g. for external encoding), clamp or reject oversized values explicitly.

Example fix

// before
offset: Int32 = 5000000000
// after
offset: Int = 5000000000

Defensive patterns

Strategy: validation

Validate before calling

// Pkl: range-check before assigning to Int32
function toInt32(v: Int): Int32 =
  if (v.isBetween(-2147483648, 2147483647)) v else throw("Int32 out of range: \(v)")

Type guard

value is Int && value >= -2147483648 && value <= 2147483647

Prevention

Remember Pkl Ints are arbitrary precision; Int32 fields can overflow.
Use plain Int unless a downstream system requires 32-bit width.
Validate timestamps/offsets against Int32 range when interoperating.

When it happens

Trigger: A property typed `Int32` receives a non-Int value, or an Int outside 32-bit range such as `big: Int32 = 5000000000` (Pkl Ints are arbitrary precision, so overflow is possible).

Common situations: Timestamps in nanoseconds, byte offsets, or hashes exceeding 2^31-1 assigned to Int32 fields; interop boundaries where the target system expects 32-bit integers.

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

Appendix: source

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

    }
  }

  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
    public VmTyped getMirror() {
      return MirrorFactories.typeAliasTypeFactory.create(this);
    }

View on GitHub (pinned to f3efcbfc9b)