apple/pkl · error · VmException

invalidSupertype

invalidSupertype

Error message

invalidSupertype

What it means

A class or typealias supertype must be a declared, parameterized, or module type reference. If the parsed supertype node is any other UnresolvedTypeNode form (e.g. union, nullable, string-literal type), AstBuilder throws invalidSupertype with the offending source text. Pkl requires supertypes to be nominal so subtype relationships are well-defined.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java:1922

          var supertypeCtx = clazz.getSuperClass();

          // needs to be inside `enterClass` so that class' type parameters are in scope
          var supertypeNode =
              supertypeCtx != null
                  ? visitType(supertypeCtx)
                  : isBaseModule && className == org.pkl.core.runtime.Identifier.ANY
                      ? null
                      : new UnresolvedTypeNode.Declared(
                          VmUtils.unavailableSourceSection(),
                          resolveBaseModuleClass(
                              org.pkl.core.runtime.Identifier.TYPED, BaseModule::getTypedClass));

          if (!(supertypeNode == null
              || supertypeNode instanceof UnresolvedTypeNode.Declared
              || supertypeNode instanceof UnresolvedTypeNode.Parameterized
              || supertypeNode instanceof UnresolvedTypeNode.Module)) {
            throw exceptionBuilder()
                .evalError("invalidSupertype", supertypeNode.getSourceSection().getCharacters())
                .withSourceSection(supertypeNode.getSourceSection())
                .build();
          }

          var classInfo =
              PClassInfo.get(
                  moduleInfo.getModuleName(),
                  className.toString(),
                  moduleInfo.getModuleKey().getUri());
          var propertyNames = CollectionUtils.<String>newHashSet(properties.size());

          var classNode =
              new ClassNode(
                  sourceSection,
                  headerSection,
                  createDocSourceSection(clazz.getDocComment()),
                  annotations,

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Extend a single declared class (or a parameterized one, e.g. `extends List<Int>`).
2. Remove the extends clause and use a type-constrained property instead.
3. Check the highlighted supertype text and replace the non-nominal type with the concrete class you meant.

Example fix

// before
class Named extends String?(name) {}

// after
class Named extends Base.Named {}

// Validate supertype is a plain nominal reference before writing:
if (!supertype.matches("[A-Za-z_][\\w.]*([<].*[>])?")) {
  throw new IllegalArgumentException("supertype must be a declared/parameterized type: " + supertype);
}

boolean isNominalTypeRef(String t) { return t != null && t.matches("[A-Za-z_][\\w.]*(<.*>)?"); }

When it happens

Trigger: Writing `class Foo extends SomeUnionType` or `extends String?`/`extends "x"|Number` — any supertype expression that parses to an UnresolvedTypeNode other than Declared, Parameterized, or Module.

Common situations: Trying to extend a union or nullable type; using a predicate or quoted-string type as a parent class; refactoring types so a parent became a union without updating the extends clause.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• cannotExtendExternalClass
• noImplementationForAbstractMethod
• noImplementationForAbstractMethods
• cannotFindMember
• cannotInstantiateAbstractClass

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