{"record":{"id":"f8098c4bb7bb7942","repo":"apple/pkl","slug":"cannot-convert-pkl-base-int-s-to-java-lang-inte","errorCode":null,"errorMessage":"Cannot convert pkl.base#Int `%s` to java.lang.Integer because it is outside range `%s..%s`","messagePattern":"Cannot convert pkl\\.base#Int `(.+?)` to java\\.lang\\.Integer 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":81,"sourceCode":"              throw new ConversionException(\n                  String.format(\n                      \"Cannot convert pkl.base#Int `%s` to java.lang.Short because it is outside range `%s..%s`\",\n                      value, Short.MIN_VALUE, Short.MAX_VALUE));\n            }\n            return value.shortValue();\n          });\n\n  /**\n   * Conversion from {@code pkl.base#Int} to {@link Integer}. Throws {@link ConversionException} if\n   * the value is too large.\n   */\n  public static final Conversion<Long, Integer> pIntToInteger =\n      Conversion.of(\n          PClassInfo.Int,\n          int.class,\n          (value, mapper) -> {\n            if (value < Integer.MIN_VALUE || value > Integer.MAX_VALUE) {\n              throw new ConversionException(\n                  String.format(\n                      \"Cannot convert pkl.base#Int `%s` to java.lang.Integer because it is outside range `%s..%s`\",\n                      value, Integer.MIN_VALUE, Integer.MAX_VALUE));\n            }\n            return value.intValue();\n          });\n\n  /** Conversion from {@code pkl.base#Int} to {@link Float}. May lose precision. */\n  public static final Conversion<Long, Float> pIntToFloat =\n      Conversion.of(PClassInfo.Int, float.class, (value, mapper) -> value.floatValue());\n\n  /** Conversion from {@code pkl.base#Int} to {@link Double}. May lose precision. */\n  public static final Conversion<Long, Double> pIntToDouble =\n      Conversion.of(PClassInfo.Int, double.class, (value, mapper) -> value.doubleValue());\n\n  /** Conversion from {@code pkl.base#Int} to {@link BigInteger}. */\n  public static final Conversion<Long, BigInteger> pIntToBigInteger =\n      Conversion.of(PClassInfo.Int, BigInteger.class, (value, mapper) -> BigInteger.valueOf(value));","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java#L63-L99","documentation":"Conversions.pIntToInteger narrows a 64-bit Pkl Int to a Java 32-bit int and throws ConversionException when the value lies outside Integer.MIN_VALUE..Integer.MAX_VALUE. Because Pkl Int is 64-bit, values beyond ~±2.1 billion cannot be represented losslessly as int and are rejected rather than truncated.","triggerScenarios":"Mapping a Pkl Int property to a Java int/Integer where the value exceeds 2147483647 or is below -2147483648 — e.g. byte counts, epoch nanos, large IDs in .pkl mapped by JavaMapper/generated code.","commonSituations":"File sizes or byte lengths exceeding 2GB configured in .pkl; millisecond epoch timestamps that fit but nanosecond ones that don't; IDs generated outside the int range; Java schema still using int after Pkl values grew.","solutions":["Widen the Java target type to long (use pIntToLong / getLong) so the full 64-bit value is preserved.","Fix the value in the .pkl source if it should not exceed int range.","Add a Pkl constraint (IntMatching(-2147483648..2147483647)) so overflow fails at evaluation time.","Pre-check the value range in Java before requesting the int mapping."],"exampleFix":"// before\nint bytes = mapper.getInt(\"maxUploadBytes\"); // throws for 10_000_000_000\n// after\nlong bytes = mapper.getLong(\"maxUploadBytes\");","handlingStrategy":"validation","validationCode":"// validate before mapping to int\nstatic int checkedToInt(long value) {\n  if (value < Integer.MIN_VALUE || value > Integer.MAX_VALUE)\n    throw new IllegalArgumentException(\"value \" + value + \" outside int range\");\n  return (int) value;\n}","typeGuard":"static boolean fitsInInt(long v) { return v >= Integer.MIN_VALUE && v <= Integer.MAX_VALUE; }","tryCatchPattern":"try {\n  Integer i = mapper.map(value, Integer.class);\n} catch (ConversionException e) {\n  log.error(\"Pkl Int out of int range, using long instead: {}\", e.getMessage());\n  return mapper.map(value, Long.class);\n}","preventionTips":["Default to long for byte counts, timestamps, and IDs that may exceed 2^31-1","Constrain Pkl properties with IntMatching(...) when int is intended","Add boundary-value tests to the mapping layer","Never assume a Pkl Int fits an int — it is 64-bit"],"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"}