apple/pkl · error · ConversionException

Cannot convert pkl.base#Int `%s` to java.lang.Short because

Error message

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

What it means

Conversions.pIntToShort narrows a 64-bit Pkl Int to a Java short and throws ConversionException when the value is outside Short.MIN_VALUE..Short.MAX_VALUE (-32768..32767). This guards against silent truncation when mapping Pkl config integers onto Java short fields.

Source

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

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

  /**
   * Conversion from {@code pkl.base#Int} to {@link Short}. Throws {@link ConversionException} if
   * the value is too large.
   */
  public static final Conversion<Long, Short> pIntToShort =
      Conversion.of(
          PClassInfo.Int,
          short.class,
          (value, mapper) -> {
            if (value < Short.MIN_VALUE || value > Short.MAX_VALUE) {
              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(

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Correct the value in the .pkl file so it fits in -32768..32767.
  2. Widen the Java field/mapping to int or long and update the conversion to pIntToInteger/pIntToLong.
  3. Add a Pkl-level type constraint (IntMatching(-32768..32767)) so invalid data is rejected at evaluation time.
  4. Pre-validate the value in code before mapping.

Example fix

// before
short timeout = mapper.getShort("timeoutMs"); // throws for 60000
// after
int timeout = mapper.getInt("timeoutMs"); // or long
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

static boolean fitsInShort(long v) { return v >= -32768 && v <= 32767; }

Try / catch

try {
  Short s = mapper.map(value, Short.class);
} catch (ConversionException e) {
  log.error("Pkl Int out of short range: {}", e.getMessage());
  throw new ConfigValidationException("expected short-sized value, got: " + value, e);
}

Prevention

When it happens

Trigger: Mapping a Pkl Int property to a Java short/Short field where the value exceeds the 16-bit range, e.g. via JavaMapper or generated config classes during decode.

Common situations: Large counters, ports above 32767, timestamps, or IDs stored in .pkl where Java code declares short; Pkl schema loosened to plain Int while Java mapping still uses Short.

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