apple/pkl · error · ConversionException

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

Error message

Cannot convert pkl.base#Int `$value` to kotlin.ULong because it is outside range `0...${Long.MAX_VALUE}`

What it means

Converting a Pkl Int (64-bit signed Long) to kotlin.ULong is only allowed for values >= 0, since the mapping refuses negative values even though ULong could hold them. Negative Pkl Ints cannot be represented by this conversion. Throw when value < 0.

Solutions

Fix the Pkl value to be >= 0.
Convert to Long instead of ULong if negative sentinels are legitimate.
Validate the value in Pkl (e.g. `value: Int(this >= 0)`) so misconfiguration fails at config validation time.
In Kotlin, convert to Long? and map the sentinel before requesting ULong.

Example fix

// before (Pkl)
retries: Int = -1
// after (Pkl)
retries: Int(this >= 0) = 3

Defensive patterns

Strategy: validation

Validate before calling

val v: Long = config["value"]
require(v >= 0) { "value must be >= 0 to convert to ULong, got $v" }

Type guard

fun Long.toULongSafe(): ULong? = if (this >= 0) toULong() else null

Try / catch

val n = try {
  config.to<ULong>()
} catch (e: ConversionException) {
  0uL // or surface a config-validation error
}

Prevention

Constrain Pkl properties with `Int(this >= 0)` so bad values fail at config validation.
Avoid negative sentinel values in fields consumed as unsigned numbers.
Prefer Long/ULong over narrower unsigned types when values may grow.

When it happens

Trigger: Calling config.to<ULong>() (or mapper conversion pIntToULong) where the Pkl Int value is negative, e.g. `offset: Int = -1`.

Common situations: Pkl config uses -1 as a sentinel ('unlimited', 'unset') and the Kotlin side expects an unsigned counter type.

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

Appendix: source

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

 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.pkl.config.kotlin.mapper

import java.util.*
import java.util.regex.Pattern
import org.pkl.config.java.mapper.Conversion
import org.pkl.config.java.mapper.ConversionException
import org.pkl.core.PClassInfo

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

View on GitHub (pinned to f3efcbfc9b)