{"record":{"id":"d84cab5bf04832c3","repo":"apple/pkl","slug":"cannotextendexternalclass","errorCode":"cannotExtendExternalClass","errorMessage":"cannotExtendExternalClass","messagePattern":"cannotExtendExternalClass","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/member/ClassNode.java","lineNumber":201,"sourceCode":"            .evalError(\"cannotExtendFinalModule\", superclass.getModuleName())\n            .withSourceSection(supertypeNode.getSourceSection())\n            .build();\n      }\n    } else {\n      if (cachedClass == superclass) {\n        throw exceptionBuilder()\n            .evalError(\"classCannotExtendSelf\", superclass.getDisplayName())\n            .withSourceSection(supertypeNode.getSourceSection())\n            .build();\n      }\n      if (superclass.isClosed()) {\n        throw exceptionBuilder()\n            .evalError(\"cannotExtendFinalClass\", superclass.getDisplayName())\n            .withSourceSection(supertypeNode.getSourceSection())\n            .build();\n      }\n      if (superclass.isExternal() && !classInfo.isStandardLibraryClass()) {\n        throw new VmExceptionBuilder()\n            .evalError(\"cannotExtendExternalClass\", superclass.getDisplayName())\n            .withSourceSection(supertypeNode.getSourceSection())\n            .build();\n      }\n    }\n  }\n}\n","sourceCodeStart":183,"sourceCodeEnd":209,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/member/ClassNode.java#L183-L209","documentation":"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.","triggerScenarios":"Declaring `class Foo extends SomeExternalClass` in Pkl source where SomeExternalClass.isExternal() is true and the declaring class is not a standard-library class.","commonSituations":"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.","solutions":["Do not extend the external class; use composition instead — hold an instance of it as a property and delegate.","Extend the nearest non-external Pkl base class that provides the behavior you need.","If the goal is to customize a stdlib type, check for official extension points (mixins, function parameters) instead of subclassing."],"exampleFix":"// before (Pkl)\nclass MyThing extends ExternalBase { ... }\n// after\nclass MyThing extends PklBase { // or another non-external class\n  base: ExternalBase\n  ...delegate methods...\n}","handlingStrategy":"validation","validationCode":"// Pkl-side check before defining the subclass\nif (someExternalClass.getClassInfo().isExternal) {\n  error(\"cannot extend external class ${someExternalClass.name}; use composition\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never subclass external/host-backed classes from Pkl source.","Prefer composition or delegation for external class behavior.","Check class documentation for designated extension points/mixins."],"tags":["inheritance","external-class","class-definition","pkl"],"backgroundTag":"invalid-argument-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}