apple/pkl · error · ConversionException

Cannot convert pkl.base#Int `%s` to java.lang.Integer becaus

Error message

Cannot convert pkl.base#Int `%s` to java.lang.Integer because it is outside range `%s..%s`

What it means

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.

Source

Thrown at pkl-config-java/src/main/java/org/pkl/config/java/mapper/Conversions.java:81

              throw new ConversionException(
                  String.format(
                      "Cannot convert pkl.base#Int `%s` to java.lang.Short because it is outside range `%s..%s`",
                      value, Short.MIN_VALUE, Short.MAX_VALUE));
            }
            return value.shortValue();
          });

  /**
   * Conversion from {@code pkl.base#Int} to {@link Integer}. Throws {@link ConversionException} if
   * the value is too large.
   */
  public static final Conversion<Long, Integer> pIntToInteger =
      Conversion.of(
          PClassInfo.Int,
          int.class,
          (value, mapper) -> {
            if (value < Integer.MIN_VALUE || value > Integer.MAX_VALUE) {
              throw new ConversionException(
                  String.format(
                      "Cannot convert pkl.base#Int `%s` to java.lang.Integer because it is outside range `%s..%s`",
                      value, Integer.MIN_VALUE, Integer.MAX_VALUE));
            }
            return value.intValue();
          });

  /** Conversion from {@code pkl.base#Int} to {@link Float}. May lose precision. */
  public static final Conversion<Long, Float> pIntToFloat =
      Conversion.of(PClassInfo.Int, float.class, (value, mapper) -> value.floatValue());

  /** Conversion from {@code pkl.base#Int} to {@link Double}. May lose precision. */
  public static final Conversion<Long, Double> pIntToDouble =
      Conversion.of(PClassInfo.Int, double.class, (value, mapper) -> value.doubleValue());

  /** Conversion from {@code pkl.base#Int} to {@link BigInteger}. */
  public static final Conversion<Long, BigInteger> pIntToBigInteger =
      Conversion.of(PClassInfo.Int, BigInteger.class, (value, mapper) -> BigInteger.valueOf(value));

View on GitHub (pinned to f3efcbfc9b)

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.

Example fix

// before
int bytes = mapper.getInt("maxUploadBytes"); // throws for 10_000_000_000
// after
long bytes = mapper.getLong("maxUploadBytes");

Defensive patterns

Strategy: validation

Validate before calling

// validate before mapping to int
static int checkedToInt(long value) {
  if (value < Integer.MIN_VALUE || value > Integer.MAX_VALUE)
    throw new IllegalArgumentException("value " + value + " outside int range");
  return (int) value;
}

Type guard

static boolean fitsInInt(long v) { return v >= Integer.MIN_VALUE && v <= Integer.MAX_VALUE; }

Try / catch

try {
  Integer i = mapper.map(value, Integer.class);
} catch (ConversionException e) {
  log.error("Pkl Int out of int range, using long instead: {}", e.getMessage());
  return mapper.map(value, Long.class);
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

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