apple/pkl · error · VmException

typeAliasMustBeLocal

typeAliasMustBeLocal

Error message

typeAliasMustBeLocal

What it means

Analogous to classMustBeLocal but for type aliases: type aliases inside a module or object amendment must be declared `local`, otherwise the amendment would introduce a new externally visible type name. AstBuilder raises typeAliasMustBeLocal with the alias header section when the amend check fails.

Source

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

    for (var clazz : classes) {
      ObjectMember member = visitClass(clazz);

      if (moduleInfo.isAmend() && !member.isLocal()) {
        throw exceptionBuilder()
            .evalError("classMustBeLocal")
            .withSourceSection(member.getHeaderSection())
            .build();
      }

      checkDuplicateMember(member.getName(), member.getHeaderSection(), propertyNames);
      EconomicMaps.put(result, member.getName(), member);
    }

    for (var typeAlias : typeAliases) {
      var member = visitTypeAlias(typeAlias);

      if (moduleInfo.isAmend() && !member.isLocal()) {
        throw exceptionBuilder()
            .evalError("typeAliasMustBeLocal")
            .withSourceSection(member.getHeaderSection())
            .build();
      }

      checkDuplicateMember(member.getName(), member.getHeaderSection(), propertyNames);
      EconomicMaps.put(result, member.getName(), member);
    }

    for (var ctx : properties) {
      var member =
          doVisitObjectProperty(
              ctx,
              ctx.getModifiers(),
              ctx.getName(),
              ctx.getTypeAnnotation(),
              ctx.getExpr(),
              ctx.getBodyList());

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Add `local`: `local typealias Foo = ...`.
2. Move the typealias into the base module.
3. Inline the aliased type in the amendment if used only once.

Example fix

// before (in an amendment)
typealias Port = Int(isBetween(1, 65535))

// after
local typealias Port = Int(isBetween(1, 65535))

// Verify typealiases declared in amendment files are local:
if (isAmendmentFile(file) && line.matches("\\s*typealias\\s+\\w+.*")) {
  report(file, lineNo, "typealiases in amendments must be `local`");
}

When it happens

Trigger: Declaring `typealias Foo = ...` inside a module amendment (moduleInfo.isAmend()) without the `local` keyword.

Common situations: Adding shared type aliases to an override file that extends a base module; scaffolding amendment files by copying base-module boilerplate that contains typealias declarations.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• classMustBeLocal
• nonLocalObjectPropertyCannotHaveTypeAnnotation
• cannotAmendPropertyDefinition
• Values of type `TypeAlias` cannot be rendered as Properties.
• ${errorMessage} This will be an error in a future release.

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