apple/pkl · error

invalidSupertype

invalidSupertype

Error message

invalidSupertype

What it means

Pkl throws invalidSupertype when a class (or module) declares a supertype that resolves to something that is not an actual class. During class initialization, ClassNode.checkSupertype validates the resolved superclass; if the superclass is null — meaning the type reference did not resolve to a VmClass — the declaration is rejected. This keeps the inheritance graph well-formed before any evaluation of the class body.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/member/ClassNode.java:169

        cachedClass.addProperty(node.execute(frame, cachedClass));
      }

      for (var node : unresolvedMethodNodes) {
        cachedClass.addMethod(node.execute(frame, cachedClass));
      }

      cachedClass.onOwnClassInitialized();
      localContext.endClassInit();
      return cachedClass;
    } catch (Throwable e) {
      localContext.clearClassInitState();
      throw e;
    }
  }

  private void checkSupertype(TypeNode supertypeNode, @Nullable VmClass superclass) {
    if (superclass == null) {
      throw exceptionBuilder()
          .evalError("invalidSupertype", supertypeNode.getSourceSection().getCharacters())
          .withSourceSection(supertypeNode.getSourceSection())
          .build();
    }
    if (moduleInfo != null) {
      if (cachedClass == superclass) {
        throw exceptionBuilder()
            .evalError("moduleCannotExtendSelf", moduleInfo.getModuleName())
            .withSourceSection(supertypeNode.getSourceSection())
            .build();
      }
      if (superclass.isClosed()) {
        throw exceptionBuilder()
            .evalError("cannotExtendFinalModule", superclass.getModuleName())
            .withSourceSection(supertypeNode.getSourceSection())
            .build();
      }
    } else {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Check the identifier after `extends` in the error's highlighted source section and confirm it names a class.
2. Fix the spelling or import path so it points at the intended class.
3. If you meant to inherit type constraints only, use `typechecked` or a type annotation instead of `extends`.
4. Ensure the imported module actually exports the class you are extending.

Example fix

// before
module my_config

extends baseConfg  // typo, resolves to nothing

// after
extends BaseConfig

// Verify the extends target is a real class before relying on it:
import "mylib.pkl"
// mylib.pkl must contain: class BaseConfig { ... }
// In tooling/tests, render the module to fail fast:
// pkl eval my_config.pkl  -> invalidSupertype surfaces at definition time

When it happens

Trigger: Declaring `extends X` where X resolves to a non-class value (object, property, function, type alias to a non-class); misspelling a class name so the identifier resolves to nothing usable; extending a module-level property instead of a class.

Common situations: Typo in a class name in an `extends` clause; refactoring renames a class leaving a stale supertype reference; accidentally extending an object or a type alias rather than a class; importing the wrong module and inheriting from a similarly named non-class member.

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
• cannotResolveTypeForProtobuf
• invalidSupertype

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