apple/pkl · warning

${errorMessage} This will be an error in a future release.

Error message

${errorMessage} This will be an error in a future release.

What it means

AstBuilder.checkModuleType detects Pkl source that declares a module type in a way that is currently tolerated but will become an error. Instead of throwing, it logs a deprecation warning with the specific errorMessage and a stack frame pointing at the offending source section.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java:428

          var parentScope = scope.getParent();
          assert parentScope != null;
          // if the parent also has "ALL", we haven't found the originating const property/method
          // yet.
          if (parentScope.getConstLevel() == ConstLevel.ALL) {
            continue;
          }
          var message =
              scope.isPropertyScope() ? "invalidModuleTypeInProperty" : "invalidModuleTypeInMethod";
          errorMessage = ErrorMessages.create(message, scope.getQualifiedName());
          break;
        }
      }
    }
    assert errorMessage != null;
    // TODO: when making this an error, update comment on moduleClass in ReferenceTypeNode.eval
    VmContext.get(null)
        .getLogger()
        .warn(
            errorMessage + " This will be an error in a future release.",
            VmUtils.createStackFrame(sourceSection, null));
  }

  @Override
  public UnresolvedTypeNode visitThisType(ThisType type) {
    var sourceSection = createSourceSection(type);
    // need to pass explicit class name for property and method arg/return type annotations.
    // this is because type annotations on class properties/methods are initialized when the
    // ClassNode
    // is executed, and the frame's receiver is the enclosing module rather than the class.
    // do not need: when in any object or at the module level (where `this` is the receiver's class)
    org.pkl.core.runtime.Identifier className = null;
    for (var scope = symbolTable.getCurrentScope(); scope != null; scope = scope.getParent()) {
      if (scope.isObjectScope() || scope.isCustomThisScope()) {
        break;
      }
      if (scope instanceof ClassScope foundClassScope) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Read the logged errorMessage to identify the exact module-type usage.
2. Update the module to declare/consume the module type per current Pkl conventions.
3. Fix moduleClass references in modules per the note in ReferenceTypeNode.eval.
4. Test module evaluation on the newest pkl-core to catch the upcoming hard error.

Example fix

// before (Pkl)
typealias MyModule = ModuleTypeUsedIncorrectly
// after
class MyModule extends BaseModule {} // use current module declaration style

// CI check: run pkl evaluation with warnings-as-errors to surface future-breaking module type usage
pkl eval --no-cache module.pkl 2>&1 | tee eval.log
grep -q "This will be an error in a future release" eval.log && exit 1 || true

When it happens

Trigger: Compiling/evaluating a Pkl module whose module type usage (via visitModuleType) triggers the deprecated pattern — e.g. referencing a class as a module type in a way future releases will forbid.

Common situations: Older Pkl codebases evaluated on newer pkl-core, code that relied on lenient module-type references, migration audits before upgrading Pkl.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Method `${qualifiedName}` is deprecated: ${deprecation}
• duplicateDefinition
• classMustBeLocal
• typeAliasMustBeLocal
• nonLocalObjectPropertyCannotHaveTypeAnnotation

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