{"record":{"id":"f108b4daf8d14ddf","repo":"apple/pkl","slug":"type-constraint-violation-int-value-out-of-range","errorCode":null,"errorMessage":"type constraint violation: Int value out of range for this type alias","messagePattern":"type constraint violation: Int value out of range for this type alias","errorType":"exception","errorClass":"VmTypeMismatchException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java","lineNumber":2543,"sourceCode":"\n  protected abstract static class IntMaskSlotTypeNode extends IntSlotTypeNode {\n    protected final long mask;\n\n    IntMaskSlotTypeNode(long mask) {\n      super(VmUtils.unavailableSourceSection());\n      this.mask = mask;\n    }\n\n    @Override\n    protected final Object executeLazily(VirtualFrame frame, Object value) {\n      var typealias = getVmTypeAlias();\n      assert typealias != null;\n      if (value instanceof Long l) {\n        if ((l & mask) == l) return value;\n\n        CompilerDirectives.transferToInterpreterAndInvalidate();\n        var sourceSection = typealias.getConstraintSection();\n        throw constraintException(value, sourceSection);\n      }\n\n      throw new VmTypeMismatchException.Simple(\n          typealias.getBaseTypeSection(), value, BaseModule.getIntClass());\n    }\n\n    @Override\n    public final VmClass getVmClass() {\n      return BaseModule.getIntClass();\n    }\n\n    @Override\n    public final VmTyped getMirror() {\n      return MirrorFactories.typeAliasTypeFactory.create(this);\n    }\n\n    @Override\n    public final boolean doIsEquivalentTo(TypeNode other) {","sourceCodeStart":2525,"sourceCodeEnd":2561,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java#L2525-L2561","documentation":"Thrown by an Int-range-constrained type alias check: a Long value is outside the bit-range the alias allows (checked with a bit mask), so the constraint section reports an out-of-range type constraint violation. Non-Long values instead raise a simple Int type mismatch.","triggerScenarios":"A value assigned to an Int subtype alias (e.g. Int8/Int16/UInt8-style constrained aliases, or user aliases with `c` constraint ranges) exceeds the representable range — e.g. 300 for UInt8, or a negative number for an unsigned alias.","commonSituations":"Port numbers, byte values, or enum-like numeric constants exceeding the alias range; converting from wider integers in codegen; config values copied from examples with larger ranges.","solutions":["Clamp or change the value to fit the alias's allowed range (verify the alias's constraint, e.g. 0..255 for UInt8).","Widen the annotation to a larger Int alias (e.g. Int16/Int32) if larger values are legitimate.","Check for sign errors where negative values hit unsigned aliases.","Validate numeric config inputs against the expected range at the source."],"exampleFix":"// before\nb: UInt8 = 300\n\n// after\nb: UInt8 = 255 // or change type to Int16 for values > 255","handlingStrategy":"validation","validationCode":"function inRange(v: Int, min: Int, max: Int): Boolean = v >= min && v <= max // e.g. UInt8: 0..255","typeGuard":"function isUInt8(v: Int): Boolean = v is Int && v >= 0 && v <= 255","tryCatchPattern":null,"preventionTips":["Check each Int alias's constraint range before assigning.","Clamp or widen types for values near range boundaries.","Watch for negatives assigned to unsigned aliases.","Validate numeric inputs at config authoring time."],"tags":["pkl","range","int","type-constraint"],"backgroundTag":"value-out-of-range","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}