apple/pkl · error · VmException

mappingAmendmentCannotHaveParameters

mappingAmendmentCannotHaveParameters

Error message

Expected a function that returns a `Mapping`, but got a `Mapping`.

What it means

A Mapping amendment must be a plain object literal; it cannot declare function parameters because the amended target is a `Mapping` value, not a parameterized constructor. `checkIsValidMappingAmendment` throws this when `parametersDescriptor` is non-null, i.e. the amendment literal has a parameter list.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/literal/SpecializedObjectLiteralNode.java:189

  protected final boolean checkIsValidMappingAmendment() {
    if (checkedIsValidMappingAmendment) return true;

    for (var member : EconomicMaps.getValues(members)) {
      if (member.isLocal()) continue;

      var memberName = member.getNameOrNull();
      if (memberName == null) continue;

      if (memberName != Identifier.DEFAULT) {
        throw exceptionBuilder()
            .evalError("objectCannotHaveProperty", BaseModule.getMappingClass())
            .withSourceSection(member.getHeaderSection())
            .build();
      }
    }

    if (parametersDescriptor != null) {
      throw exceptionBuilder()
          .evalError("mappingAmendmentCannotHaveParameters")
          .withSourceSection(getParentNode().getSourceSection())
          .build();
    }

    checkedIsValidMappingAmendment = true;
    return true;
  }

  @Idempotent
  protected final boolean checkMaxListingMemberIndex(int parentLength) {
    assert maxListingMemberIndex != Long.MIN_VALUE;
    if (maxListingMemberIndex < parentLength) return true;

    CompilerDirectives.transferToInterpreter();
    var cursor = EconomicMaps.getEntries(members);
    while (cursor.advance()) {
      var key = cursor.getKey();

View on GitHub (pinned to f3efcbfc9b)

Solutions

Remove the parameter list from the Mapping amendment and write entries directly
Parameterize at a higher level: put the parameterized logic in a function that returns the Mapping, then assign it
If dynamic keying is needed, compute keys in normal expressions within entries

Example fix

// before
mymap { (k) { [k] = 1 } }
// after
mymap { ["key"] = 1 }

Defensive patterns

Strategy: validation

Validate before calling

// Mapping amendments take no parameter list: write mymap { [k] = v } not mymap { (k) { ... } }

Prevention

Only class-amending literals support parameter lists
Compute dynamic keys with normal expressions inside entries

When it happens

Trigger: Writing a parameterized amendment such as `mymap { (key) { ... } }` or an `amends (x) -> ...` form targeting a Mapping-typed value.

Common situations: Reusing a class-amendment pattern (which supports parameters) on a Mapping; templated config generation that assumed parameterized Mapping amendments exist.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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