apple/pkl · error

cannotExtendFinalModule

cannotExtendFinalModule

Error message

cannotExtendFinalModule

What it means

Pkl throws cannotExtendFinalModule when a class or module tries to extend a module that is 'closed' (declared final, e.g. via an open/closed module annotation or being a sealed standard-library module). ClassNode.checkSupertype rejects inheritance from a closed superclass because closed modules promise no further subclassing. The error names the module being illegally extended.

Source

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

    }
  }

  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 {
      if (cachedClass == superclass) {
        throw exceptionBuilder()
            .evalError("classCannotExtendSelf", superclass.getDisplayName())
            .withSourceSection(supertypeNode.getSourceSection())
            .build();
      }
      if (superclass.isClosed()) {
        throw exceptionBuilder()
            .evalError("cannotExtendFinalClass", superclass.getDisplayName())
            .withSourceSection(supertypeNode.getSourceSection())
            .build();
      }
      if (superclass.isExternal() && !classInfo.isStandardLibraryClass()) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Stop extending the closed module; instead import it and compose (use its properties/defaults) rather than inherit.
2. Copy the needed defaults into your own module if extension is essential.
3. If you own the superclass module, mark it `open` to permit subclassing.
4. Check the superclass module's documentation for the sanctioned customization mechanism.

Example fix

// before
module my_server
extends "@server/ClosedModule.pkl"  // closed module

// after
module my_server
import "@server/ClosedModule.pkl"
server = new ClosedModule { /* overrides via object literal if allowed */ }

// Before extending a library module, confirm it is open:
// the module file must be declared `open module ...` (absence means closed/final).
// pkl eval my_module.pkl  -> cannotExtendFinalModule surfaces at definition

When it happens

Trigger: Writing `extends` with a superclass whose module is annotated final/closed (isClosed() returns true) and the enclosing node is a module; extending a closed standard-library module.

Common situations: Trying to customize behavior by inheriting from a closed library module; upgrading Pkl where a previously open module became closed; attempting to extend built-in modules such as pkl base modules that prohibit extension.

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

• moduleCannotExtendSelf
• cannotExtendExternalClass
• noImplementationForAbstractMethod
• noImplementationForAbstractMethods
• externalClass

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