apple/pkl · error · ConversionException

Cannot convert pkl.base#Int `$value` to kotlin.UByte…

Error message

Cannot convert pkl.base#Int `$value` to kotlin.UByte because it is outside range `0...$max`

What it means

Range validation in KotlinConversions.pIntToUByte: a pkl.base#Int is converted to kotlin.UByte only if it fits 0..255 (0xFF); otherwise ConversionException is thrown. The input at fault is a negative Long or a Long above 255 used where a UByte is required.

Solutions

Validate or clamp the value to 0..255 before conversion.
Choose a wider Kotlin numeric type for the target property.

Example fix

// before
val alpha: UByte = config.to<UByte>() // value: 300
// after
val alpha: UInt = config.to<UInt>()

Defensive patterns

Strategy: validation

Validate before calling

val v: Long = config["octet"]
require(v in 0..255) { "octet must fit in UByte (0..255), got $v" }

Type guard

fun Long.toUByteSafe(): UByte? = if (this in 0..255) toUByte() else null

Try / catch

val octet = try {
  config.to<UByte>()
} catch (e: ConversionException) {
  0uB // or fail fast with context
}

Prevention

Constrain Pkl properties: `octet: Int(isBetween(0, 255))`.
For RGB/protocol byte fields, validate components in Pkl before export.
Use a wider type when the semantic range is unclear.

When it happens

Trigger: config.to<UByte>() on a Pkl Int outside 0..255, e.g. a byte-size or octet field set to 300 or -1.

Common situations: Small numeric fields (protocol octets, RGB components) configured with out-of-range values; negative sentinels.

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

Appendix: source

Thrown at pkl-config-kotlin/src/main/kotlin/org/pkl/config/kotlin/mapper/KotlinConversions.kt:65

    }

  val pIntToUShort: Conversion<Long, UShort> =
    Conversion.of(PClassInfo.Int, UShort::class.java) { value, _ ->
      val max = 0xFFFF // use literal instead of `UShort.MAX_VALUE.toLong()`
      if (value < 0 || value > max) {
        throw ConversionException(
          "Cannot convert pkl.base#Int `$value` to kotlin.UShort " +
            "because it is outside range `0...$max`"
        )
      }
      value.toUShort()
    }

  val pIntToUByte: Conversion<Long, UByte> =
    Conversion.of(PClassInfo.Int, UByte::class.java) { value, _ ->
      val max = 0xFF // use literal instead of `UByte.MAX_VALUE.toLong()`
      if (value < 0 || value > max) {
        throw ConversionException(
          "Cannot convert pkl.base#Int `$value` to kotlin.UByte " +
            "because it is outside range `0...$max`"
        )
      }
      value.toUByte()
    }

  val pStringToKotlinRegex: Conversion<String, Regex> =
    Conversion.of(PClassInfo.String, Regex::class.java) { value, _ -> Regex(value) }

  val pRegexToKotlinRegex: Conversion<Pattern, Regex> =
    Conversion.of(PClassInfo.Regex, Regex::class.java) { value, _ -> value.toRegex() }

  val all: Collection<Conversion<*, *>> =
    Collections.unmodifiableList(
      listOf(
        pIntToULong,
        pIntToUInt,

View on GitHub (pinned to f3efcbfc9b)