{"record":{"id":"e9055e9eba773951","repo":"apple/pkl","slug":"cannot-convert-pkl-base-int-s-to-java-lang-byte","errorCode":null,"errorMessage":"Cannot convert pkl.base#Int `%s` to java.lang.Byte because it is outside range `%s..%s`","messagePattern":"Cannot convert pkl\\.base#Int `(.+?)` to java\\.lang\\.Byte because it is outside range `(.+?)\\.\\.(.+?)`","errorType":"exception","errorClass":"ConversionException","httpStatus":null,"severity":"error","filePath":"pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java","lineNumber":45,"sourceCode":"import java.util.*;\nimport java.util.regex.*;\nimport org.pkl.core.*;\n\n/** Predefined conversions for scalar types. */\npublic final class Conversions {\n  private Conversions() {}\n\n  /**\n   * Conversion from {@code pkl.base#Int} to {@link Byte}. Throws {@link ConversionException} if the\n   * value is too large.\n   */\n  public static final Conversion<Long, Byte> pIntToByte =\n      Conversion.of(\n          PClassInfo.Int,\n          byte.class,\n          (value, mapper) -> {\n            if (value < Byte.MIN_VALUE || value > Byte.MAX_VALUE) {\n              throw new ConversionException(\n                  String.format(\n                      \"Cannot convert pkl.base#Int `%s` to java.lang.Byte because it is outside range `%s..%s`\",\n                      value, Byte.MIN_VALUE, Byte.MAX_VALUE));\n            }\n            return value.byteValue();\n          });\n\n  /**\n   * Conversion from {@code pkl.base#Int} to {@link Short}. Throws {@link ConversionException} if\n   * the value is too large.\n   */\n  public static final Conversion<Long, Short> pIntToShort =\n      Conversion.of(\n          PClassInfo.Int,\n          short.class,\n          (value, mapper) -> {\n            if (value < Short.MIN_VALUE || value > Short.MAX_VALUE) {\n              throw new ConversionException(","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java#L27-L63","documentation":"When mapping a Pkl Int to a Java byte, Conversions.pIntToByte checks the 64-bit Pkl integer against the byte range (-128..127) and throws ConversionException if it falls outside. Pkl Ints are unbounded 64-bit values, so narrowing to Byte requires this explicit range validation instead of silent truncation.","triggerScenarios":"Decoding or mapping a Pkl property of type Int (or untyped Int value) to a Java field/parameter of type byte/Byte where the value is < -128 or > 127, e.g. via JavaMapper or generated code converting config values.","commonSituations":"A .pkl file contains a value like 300 or -500 where the Java schema expects a byte (e.g. a port, small ID, or flag); schema evolved from Byte to Int in Java but Pkl data still has large values; hand-written mapper wiring byte.class for an Int property.","solutions":["Fix the value in the .pkl source so it fits in -128..127.","Change the Java target type to short/int/long (or Integer) to widen the range, and update the conversion/mapper accordingly.","If wide values are legitimate, add a pre-validation or clamping step in your code before invoking the mapper.","Validate the Pkl schema with a constraint (e.g. value is IntMatching(-128..127)) so bad data fails at eval time."],"exampleFix":"// before: byte flag = mapper.getByte(\"level\"); // throws for 300\n// in .pkl\nlevel: Int(this >= -128 && this <= 127) = 300\n// after: widen the Java type or fix the data\nlevel: Int(this >= -128 && this <= 127) = 100\n// or in Java: short level = mapper.getShort(\"level\");","handlingStrategy":"validation","validationCode":"// validate before mapping to byte\nstatic byte checkedToByte(long value) {\n  if (value < Byte.MIN_VALUE || value > Byte.MAX_VALUE)\n    throw new IllegalArgumentException(\"value \" + value + \" outside byte range\");\n  return (byte) value;\n}","typeGuard":"static boolean fitsInByte(long v) { return v >= -128 && v <= 127; }","tryCatchPattern":"try {\n  Byte b = mapper.map(value, Byte.class);\n} catch (ConversionException e) {\n  log.error(\"Pkl Int out of byte range: {}\", e.getMessage());\n  throw new ConfigValidationException(\"expected byte-sized value, got: \" + value, e);\n}","preventionTips":["Constrain the Pkl property with IntMatching(-128..127) so bad data fails at eval time","Use int/long in Java schemas unless a byte is truly required","Validate config values in tests against realistic data","Keep generated Java types in sync with the ranges the Pkl schema allows"],"tags":["conversion","range","integer-overflow","pkl","mapping"],"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"}