apple/pkl · error · VmException

cannotExtendExternalClass

cannotExtendExternalClass

Error message

cannotExtendExternalClass

What it means

Pkl classes may extend other Pkl classes, but extending a class marked external is forbidden unless the extending class itself belongs to the standard library. External classes are backed by native/host implementation and cannot be subclassed from Pkl source. checkSupertype raises evalError "cannotExtendExternalClass" naming the superclass at the `extends` clause.

Source

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

            .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()) {
        throw new VmExceptionBuilder()
            .evalError("cannotExtendExternalClass", superclass.getDisplayName())
            .withSourceSection(supertypeNode.getSourceSection())
            .build();
      }
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Do not extend the external class; use composition instead — hold an instance of it as a property and delegate.
2. Extend the nearest non-external Pkl base class that provides the behavior you need.
3. If the goal is to customize a stdlib type, check for official extension points (mixins, function parameters) instead of subclassing.

Example fix

// before (Pkl)
class MyThing extends ExternalBase { ... }
// after
class MyThing extends PklBase { // or another non-external class
  base: ExternalBase
  ...delegate methods...
}

// Pkl-side check before defining the subclass
if (someExternalClass.getClassInfo().isExternal) {
  error("cannot extend external class ${someExternalClass.name}; use composition")
}

When it happens

Trigger: Declaring `class Foo extends SomeExternalClass` in Pkl source where SomeExternalClass.isExternal() is true and the declaring class is not a standard-library class.

Common situations: Trying to subclass built-in host-backed classes (e.g. platform/native base classes) to customize behavior; copying stdlib-like patterns that are only legal inside the Pkl standard library itself.

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

• noImplementationForAbstractMethod
• noImplementationForAbstractMethods
• externalClass
• classMustBeLocal
• invalidSupertype

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