apple/pkl · error · VmException

expectedModuleAsArgument

expectedModuleAsArgument

Error message

expectedModuleAsArgument

What it means

`module.reflect()`/reflect nodes throw `expectedModuleAsArgument` when the argument passed to a reflection API expecting a module object is not one. Pkl checks `module.isModuleObject()` and throws an evalError located at the argument. Only actual module instances (the object representing a loaded Pkl module) are acceptable.

Solutions

1. Pass the module itself: import the module and pass the imported module binding (`import "foo.pkl"; foo.reflect()` style APIs)
2. Check with `isModule` before calling if the argument comes from dynamic code
3. If you have a class and want its module, use the class's `module` property rather than the class
4. Inspect the argument's type (`value.getClass()`, `value is Module`) to confirm what you actually hold

Example fix

// before
myClass.reflectModule()
// after
import "foo.pkl"
foo.reflectModule()

if (!(arg.isModule())) {
  throw("expected a module, got ${arg.getClass().simpleName}")
}

function isModuleArg(v: Any): Boolean = v is Module

result = try { moduleApi(arg) } catch (e) { die("arg must be a module object: ${e.message}") }

When it happens

Trigger: Calling `Reflect(...)` or the `Module` reflection method with a value that is a class, typed object, String, Function, or null instead of a module object, e.g. `moduleOf(someClass)` style misuse or passing `module` from a non-module context.

Common situations: Confusing a module with its class or with a typed object instantiated from it; passing an imported value that is a class rather than the module; refactoring code where a variable previously held a module but now holds something else.

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

• cannotDefineExternalMember
• cannotFindMatchingCollectionElement
• cannotFindStdLibModule
• cannotInstantiateExternalClass
• Did not find expected Java class

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/reflect/ReflectNodes.java:35

import com.oracle.truffle.api.CompilerDirectives.TruffleBoundary;
import com.oracle.truffle.api.dsl.Specialization;
import org.pkl.core.runtime.*;
import org.pkl.core.stdlib.ExternalMethod1Node;
import org.pkl.core.stdlib.ExternalMethod2Node;
import org.pkl.core.stdlib.ExternalPropertyNode;
import org.pkl.core.util.Pair;

@SuppressWarnings("unused")
public final class ReflectNodes {
  private ReflectNodes() {}

  public abstract static class Module extends ExternalMethod1Node {
    @Specialization
    @TruffleBoundary
    protected VmTyped eval(VmTyped self, VmTyped module) {
      if (!module.isModuleObject()) {
        throw exceptionBuilder()
            .evalError("expectedModuleAsArgument")
            .withLocation(getArg1Node())
            .build();
      }
      return module.getModuleMirror();
    }
  }

  public abstract static class moduleOf extends ExternalMethod1Node {
    @Specialization
    @TruffleBoundary
    protected VmTyped eval(VmTyped self, VmTyped module) {
      var candidate = module;
      while (!candidate.isModuleObject()) {
        candidate = candidate.getParent();
        if (candidate == null) {
          throw exceptionBuilder()
              .bug("No module found in prototype chain.")

View on GitHub (pinned to f3efcbfc9b)