apple/pkl · error

commandMustNotAssignOrAmendProperty

commandMustNotAssignOrAmendProperty

Error message

commandMustNotAssignOrAmendProperty

What it means

Pkl CLI commands (e.g. codegen/eval commands built from a Pkl spec) read their option values from a base module, but that module's properties must be supplied, not computed by assignment or amendment. checkPropertyIsUndefined throws `commandMustNotAssignOrAmendProperty` naming the offending property when the property is explicitly assigned or amended in the spec module rather than left for the command to define.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java:1239

    var result = VmValue.export(VmUtils.readMember(value, key));
    return result instanceof PNull ? null : (String) result;
  }

  /** Check a value and its parents to see if any assign/amend the given property */
  private void checkPropertyIsUndefined(VmTyped value, Identifier name) {
    var member = VmUtils.findMember(value, name);
    if (member == null) return;

    var memberNode = member.getMemberNode();
    var sourceSection =
        memberNode == null
            ? member.getSourceSection()
            : memberNode.getBodyNode() instanceof DefaultPropertyBodyNode
                ? null
                : memberNode.getSourceSection();

    if (sourceSection != null) {
      throw exceptionBuilder()
          .evalError("commandMustNotAssignOrAmendProperty", name)
          .withSourceSection(sourceSection)
          .build();
    }
  }

  private VmExceptionBuilder exceptionBuilder() {
    return new VmExceptionBuilder();
  }

  // endregion
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Remove the assignment/amendment of the named property from the spec module (the error points at the exact source section).
2. If the value must be configured, supply it through the command's own CLI flag or the property the command expects to set itself.
3. Use a differently named property for your custom value.
4. Regenerate the spec module from its canonical template if it drifted.

Example fix

// before: PklProject/amend.pkl
output = new Output { ... }

// after: let the command define `output`; configure via allowed means
// (remove the line, or rename your property)
myOutput = new Output { ... }

// in your CI lint, grep the spec module for assignments to reserved properties
grep -nE '^\s*(output|format|engine)\s*=' generator.pkl && exit 1 || exit 0

When it happens

Trigger: A command's base Pkl module (e.g. a `pkl.project`/generator spec passed to a CLI command) contains `name = "x"` or an amend expression for a property the command reserves (like `output`, `format`, etc.), detected at CommandSpecParser.checkPropertyIsUndefined.

Common situations: Hand-editing a generated PklProject/CodeGenerator module and accidentally assigning a reserved property; copying spec modules between commands where property ownership differs; amending a base module to override a reserved key.

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

• +e.getMessage()
• Directory $dir does not contain a PklProject file.
• packageTestsFailed
• noPackageDefinedByProject
• missingProjectInPackageCommand

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