apple/pkl · error · ConversionException

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

Error message

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

What it means

Converting a Pkl Int to kotlin.UInt requires the value to fit in 0..0xFFFFFFFF (4294967295). Negative values or values above the 32-bit unsigned maximum are rejected because a 64-bit Pkl Int cannot be losslessly narrowed to UInt.

Solutions

  1. Correct the Pkl value to be within 0..4294967295.
  2. Use ULong or Long as the target type for larger values.
  3. Constrain the Pkl property: `port: Int(isBetween(0, 4294967295))` so errors surface as config validation.
  4. Convert to Long first and range-check in Kotlin before narrowing.

Example fix

// before
val size: UInt = config.to<UInt>() // value: 8589934592
// after
val size: ULong = config.to<ULong>()
Defensive patterns

Strategy: validation

Validate before calling

val v: Long = config["size"]
require(v in 0..0xFFFFFFFF) { "size must fit in UInt (0..4294967295), got $v" }

Type guard

fun Long.toUIntSafe(): UInt? = if (this in 0..0xFFFFFFFFL) toUInt() else null

Try / catch

val size = try {
  config.to<UInt>()
} catch (e: ConversionException) {
  error("config value out of UInt range: ${e.message}")
}

Prevention

When it happens

Trigger: config.to<UInt>() on a Pkl Int that is negative or greater than 4294967295.

Common situations: Config values like timeouts or sizes accidentally specified in bytes beyond 4 GiB, or negative placeholder values, mapped to UInt fields.

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

Appendix: source

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

object KotlinConversions {
  val pIntToULong: Conversion<Long, ULong> =
    Conversion.of(PClassInfo.Int, ULong::class.java) { value, _ ->
      if (value < 0) {
        throw ConversionException(
          "Cannot convert pkl.base#Int `$value` to kotlin.ULong " +
            // use Long.MAX_VALUE instead of ULong.MAX_VALUE
            "because it is outside range `0...${Long.MAX_VALUE}`"
        )
      }
      value.toULong()
    }

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

  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()
    }

View on GitHub (pinned to f3efcbfc9b)