apple/pkl · error · ConversionException

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

Error message

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

What it means

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.

Source

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

import java.util.*;
import java.util.regex.*;
import org.pkl.core.*;

/** Predefined conversions for scalar types. */
public final class Conversions {
  private Conversions() {}

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

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Fix the value in the .pkl source so it fits in -128..127.
  2. Change the Java target type to short/int/long (or Integer) to widen the range, and update the conversion/mapper accordingly.
  3. If wide values are legitimate, add a pre-validation or clamping step in your code before invoking the mapper.
  4. Validate the Pkl schema with a constraint (e.g. value is IntMatching(-128..127)) so bad data fails at eval time.

Example fix

// before: byte flag = mapper.getByte("level"); // throws for 300
// in .pkl
level: Int(this >= -128 && this <= 127) = 300
// after: widen the Java type or fix the data
level: Int(this >= -128 && this <= 127) = 100
// or in Java: short level = mapper.getShort("level");
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

static boolean fitsInByte(long v) { return v >= -128 && v <= 127; }

Try / catch

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

Prevention

When it happens

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

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

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