{"record":{"id":"9f8bcdb18b95f913","repo":"apple/pkl","slug":"cannot-convert-pkl-base-int-value-to-kotlin-uin","errorCode":null,"errorMessage":"Cannot convert pkl.base#Int `$value` to kotlin.UInt because it is outside range `0...$max`","messagePattern":"Cannot convert pkl\\.base#Int `\\$value` to kotlin\\.UInt because it is outside range `0\\.\\.\\.\\$max`","errorType":"exception","errorClass":"ConversionException","httpStatus":null,"severity":"error","filePath":"pkl-config-kotlin/src/main/kotlin/org/pkl/config/kotlin/mapper/KotlinConversions.kt","lineNumber":41,"sourceCode":"\nobject KotlinConversions {\n  val pIntToULong: Conversion<Long, ULong> =\n    Conversion.of(PClassInfo.Int, ULong::class.java) { value, _ ->\n      if (value < 0) {\n        throw ConversionException(\n          \"Cannot convert pkl.base#Int `$value` to kotlin.ULong \" +\n            // use Long.MAX_VALUE instead of ULong.MAX_VALUE\n            \"because it is outside range `0...${Long.MAX_VALUE}`\"\n        )\n      }\n      value.toULong()\n    }\n\n  val pIntToUInt: Conversion<Long, UInt> =\n    Conversion.of(PClassInfo.Int, UInt::class.java) { value, _ ->\n      val max = 0xFFFFFFFF // use literal instead of `UInt.MAX_VALUE.toLong()`\n      if (value < 0 || value > max) {\n        throw ConversionException(\n          \"Cannot convert pkl.base#Int `$value` to kotlin.UInt \" +\n            \"because it is outside range `0...$max`\"\n        )\n      }\n      value.toUInt()\n    }\n\n  val pIntToUShort: Conversion<Long, UShort> =\n    Conversion.of(PClassInfo.Int, UShort::class.java) { value, _ ->\n      val max = 0xFFFF // use literal instead of `UShort.MAX_VALUE.toLong()`\n      if (value < 0 || value > max) {\n        throw ConversionException(\n          \"Cannot convert pkl.base#Int `$value` to kotlin.UShort \" +\n            \"because it is outside range `0...$max`\"\n        )\n      }\n      value.toUShort()\n    }","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-config-kotlin/src/main/kotlin/org/pkl/config/kotlin/mapper/KotlinConversions.kt#L23-L59","documentation":"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.","triggerScenarios":"config.to<UInt>() on a Pkl Int that is negative or greater than 4294967295.","commonSituations":"Config values like timeouts or sizes accidentally specified in bytes beyond 4 GiB, or negative placeholder values, mapped to UInt fields.","solutions":["Correct the Pkl value to be within 0..4294967295.","Use ULong or Long as the target type for larger values.","Constrain the Pkl property: `port: Int(isBetween(0, 4294967295))` so errors surface as config validation.","Convert to Long first and range-check in Kotlin before narrowing."],"exampleFix":"// before\nval size: UInt = config.to<UInt>() // value: 8589934592\n// after\nval size: ULong = config.to<ULong>()","handlingStrategy":"validation","validationCode":"val v: Long = config[\"size\"]\nrequire(v in 0..0xFFFFFFFF) { \"size must fit in UInt (0..4294967295), got $v\" }","typeGuard":"fun Long.toUIntSafe(): UInt? = if (this in 0..0xFFFFFFFFL) toUInt() else null","tryCatchPattern":"val size = try {\n  config.to<UInt>()\n} catch (e: ConversionException) {\n  error(\"config value out of UInt range: ${e.message}\")\n}","preventionTips":["Constrain Pkl properties: `size: Int(isBetween(0, 4294967295))`.","Use ULong for byte counts/sizes that may exceed 4 GiB.","Document expected ranges on Pkl properties with doc comments."],"tags":["kotlin","unsigned","range","conversion"],"backgroundTag":"value-out-of-range","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}