apple/pkl · error · VmTypeMismatchException.Simple

VmTypeMismatchException.Simple (value is not an Int8 in…

Error message

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

What it means

Int8TypeAliasTypeNode checks the `Int8` typealias: the value must be an Int (vmClass is Int) whose value fits in the 8-bit signed range (-128..127). If it is not an in-range Int8, VmTypeMismatchException.Simple is thrown with the typealias's base-type section; out-of-range values that pass the base check are rejected by the constraint with constraintException.

Solutions

Use a value within -128..127, or clamp/convert: `value.coercedIn(-128, 127)` or `.toInt()` for strings.
Widen the annotation to `Int`, `Int16`, `Int32`, or `Int` if the range is too small.
Validate the input range at the boundary where the value enters the module.

Example fix

// before
level: Int8 = 300
// after
level: Int8 = 100

Defensive patterns

Strategy: validation

Validate before calling

// Pkl: range-check before assigning to Int8
function toInt8(v: Int): Int8 =
  if (v.isBetween(-128, 127)) v else throw("Int8 out of range: \(v)")

Type guard

value is Int && value >= -128 && value <= 127

Prevention

Clamp external values with .coercedIn(-128, 127).
Choose Int16/Int32/Int when the field can exceed byte range.
Add constraint properties to fail with domain-specific messages.

When it happens

Trigger: A property typed `Int8` receives a value that is not an Int, or an Int outside -128..127 (e.g. `tiny: Int8 = 300`, or `tiny: Int8 = "5"`).

Common situations: Ports, flags, or byte-sized fields set with values larger than 127; copying an ordinary Int into an Int8 field; string inputs from config files.

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

Appendix: source

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

    }
  }

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

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

        CompilerDirectives.transferToInterpreterAndInvalidate();
        var sourceSection = BaseModule.getInt8TypeAlias().getConstraintSection();
        throw constraintException(value, sourceSection);
      }

      throw new VmTypeMismatchException.Simple(
          BaseModule.getInt8TypeAlias().getBaseTypeSection(), value, BaseModule.getIntClass());
    }

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

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

    @Override
    public VmTyped getMirror() {
      return MirrorFactories.typeAliasTypeFactory.create(this);
    }

View on GitHub (pinned to f3efcbfc9b)