apple/pkl · error

cannotFindQualifiedType

cannotFindQualifiedType

Error message

cannotFindQualifiedType

What it means

`cannotFindQualifiedType` is thrown by ResolveQualifiedDeclaredTypeNode.executeGeneric when a qualified type `module.TypeName` cannot be resolved: neither the imported module nor any of its parent (extending/amending) modules declare the type name. The message names the type and the module that was searched.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/type/ResolveQualifiedDeclaredTypeNode.java:64

    assert moduleName.isLocalProp();
    assert typeName.isRegular();
  }

  @Override
  public Object executeGeneric(VirtualFrame frame) {
    CompilerDirectives.transferToInterpreter();

    var enclosingModule = (VmTyped) getModuleNode.executeGeneric(frame);
    var importedModule = getImport(enclosingModule, moduleName, moduleNameSection);

    // search module hierarchy
    // (type declared in base module is accessible through extending and amending modules)
    for (var currModule = importedModule; currModule != null; currModule = currModule.getParent()) {
      var result = getType(currModule, typeName, sourceSection);
      if (result != null) return result;
    }

    throw exceptionBuilder()
        .evalError(
            "cannotFindQualifiedType", typeName, importedModule.getModuleInfo().getModuleName())
        .withSourceSection(typeNameSection)
        .build();
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Fix the type name spelling or use the type's current name
  2. Import the module that actually declares the type
  3. Check the named module for the type's new location after upgrades

Example fix

// before
import "base.pkl" as base
x: base.Clsss
// after
x: base.Class
Defensive patterns

Strategy: validation

Validate before calling

// validate type exists before evaluating
if (!importedModuleExports.includes("TypeName")) throw new Error("type not found in imported module");

Prevention

When it happens

Trigger: `importedMod.MissingType` in a type position where MissingType does not exist in the imported module or its module hierarchy; typo in the type name; the type was removed/renamed upstream.

Common situations: Using a base-module class via a custom module that re-exports only some types; upgrading a dependency where a class was renamed; referring to a type from the wrong imported module.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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