apple/pkl · error · JavaCodeGeneratorException

Standard library typealias

Error message

Standard library typealias `${typeAlias.qualifiedName}` is not supported by Java code generator. If you think this is an omission, please let us know.

What it means

A standard-library type alias whose aliased type would otherwise be represented as a generated enum has no pre-mapped Java type, so generation throws. Well-known aliases (DurationUnit, DataSizeUnit, Uri) are mapped; others are unsupported, and the message asks users to report omissions.

Solutions

1. Use the concrete aliased type instead of the stdlib alias in your Pkl module.
2. Upgrade pkl-codegen-java so the alias gets mapped.
3. Define your own type alias in your module with the same string-literal union — it will generate an enum.
4. File an upstream issue requesting mapping for that alias.

Example fix

// before (Pkl)
unit: SomeStdlibAlias
// after
type MyUnit = "a" | "b"
unit: MyUnit

fun isMappedStdlibAlias(a: TypeAlias) = a.qualifiedName in setOf("pkl.base#DurationUnit","pkl.base#DataSizeUnit","pkl.base#Uri")

try { generate() } catch (e: JavaCodeGeneratorException) { if ("Standard library typealias" in e.message!!) inlineOwnAlias() else throw e }

When it happens

Trigger: A schema references a stdlib typealias (typeAlias.isStandardLibraryMember) that is enum-representable but not in the mapping (not DurationUnit/DataSizeUnit/Uri and the other handled cases).

Common situations: Referencing obscure pkl.base typealiases from your module, or using a newly added stdlib alias before the generator maps it.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Standard library typealias
• Cannot generate Kotlin code for a Pkl standard library…
• Standard library class
• Standard library class
• Annotation `$fqn` is not a valid Java class. The name of…

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/75fdbdf6af28444e. Report an issue: GitHub.

Appendix: source

Thrown at pkl-codegen-java/src/main/kotlin/org/pkl/codegen/java/JavaCodeGenerator.kt:872

      is PType.Nullable -> baseType.toJavaPoetName(nullable = true, boxed = true)
      is PType.Constrained -> baseType.toJavaPoetName(nullable = nullable, boxed = boxed)
      is PType.Alias ->
        when (typeAlias.qualifiedName) {
          "pkl.base#NonNull" -> OBJECT.nullableIf(nullable)
          "pkl.base#Int8" -> TypeName.BYTE.boxIf(boxed).nullableIf(nullable)
          "pkl.base#Int16",
          "pkl.base#UInt8" -> TypeName.SHORT.boxIf(boxed).nullableIf(nullable)
          "pkl.base#Int32",
          "pkl.base#UInt16" -> TypeName.INT.boxIf(boxed).nullableIf(nullable)
          "pkl.base#UInt",
          "pkl.base#UInt32" -> TypeName.LONG.boxIf(boxed).nullableIf(nullable)
          "pkl.base#DurationUnit" -> DURATION_UNIT.nullableIf(nullable)
          "pkl.base#DataSizeUnit" -> DATASIZE_UNIT.nullableIf(nullable)
          "pkl.base#Uri" -> URI.nullableIf(nullable)
          else -> {
            if (CodeGeneratorUtils.isRepresentableAsEnum(aliasedType, null)) {
              if (typeAlias.isStandardLibraryMember) {
                throw JavaCodeGeneratorException(
                  "Standard library typealias `${typeAlias.qualifiedName}` is not supported by Java code generator. " +
                    "If you think this is an omission, please let us know."
                )
              } else {
                // reference generated enum class
                typeAlias.toJavaPoetName().nullableIf(nullable)
              }
            } else {
              // inline type alias
              aliasedType.toJavaPoetName(nullable)
            }
          }
        }
      is PType.Function ->
        throw JavaCodeGeneratorException(
          "Pkl function types are not supported by the Java code generator."
        )
      is PType.Union ->

View on GitHub (pinned to f3efcbfc9b)