apple/pkl · error · ConversionException

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

Error message

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

What it means

Range validation in KotlinConversions.pIntToUShort: a pkl.base#Int (64-bit) is converted to kotlin.UShort only if it fits 0..65535 (0xFFFF); out-of-range values throw ConversionException. The input at fault is any negative Long or Long greater than 65535 passed to a UShort-typed target.

Solutions

Clamp or validate the Int value to 0..65535 before conversion.
Use a wider Kotlin type (Int/Long/UInt) if the value cannot fit UShort.

Example fix

// before (Pkl)
port: Int = 70000
// after (Pkl)
port: Int(isBetween(0, 65535)) = 8080

Defensive patterns

Strategy: validation

Validate before calling

val v: Long = config["port"]
require(v in 0..65535) { "port must fit in UShort (0..65535), got $v" }

Type guard

fun Long.toUShortSafe(): UShort? = if (this in 0..65535) toUShort() else null

Try / catch

val port = try {
  config.to<UShort>()
} catch (e: ConversionException) {
  0uS // or fail fast with context
}

Prevention

Constrain Pkl properties: `port: Int(isBetween(0, 65535))`.
Validate network ports at config-authoring time with pkl eval.
Use UInt for values that might exceed 16 bits.

When it happens

Trigger: config.to<UShort>() on a Pkl Int outside 0..65535, e.g. port 70000 or a negative value.

Common situations: Network port or enum-like numeric codes configured out of the 16-bit range; negative sentinel values.

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

Appendix: source

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

    }

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

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

View on GitHub (pinned to f3efcbfc9b)