apple/pkl · error · VmException

propertyMustBeConst

propertyMustBeConst

Error message

Cannot reference property `{0}` from here because it is not `const`.

What it means

Pkl throws `propertyMustBeConst` when code references a local/module property from a context that requires a `const` value (e.g. inside a `const` property definition or an annotation-like position) but the property is not declared `const`. AbstractReadLocalPropertyNode.getProperty checks needsConst && !property.isConst().

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/member/AbstractReadLocalPropertyNode.java:52

  public AbstractReadLocalPropertyNode(
      SourceSection sourceSection, Identifier name, boolean needsConst) {
    super(sourceSection);
    this.name = name;
    this.needsConst = needsConst;
  }

  protected ObjectMember getProperty(VmObjectLike owner) {
    if (property == null) {
      CompilerDirectives.transferToInterpreterAndInvalidate();
      property = owner.getMember(name);
      if (property == null) {
        // should never happen
        CompilerDirectives.transferToInterpreter();
        throw exceptionBuilder().bug("Couldn't find local variable `" + name + "`.").build();
      }
      if (needsConst && !property.isConst()) {
        throw exceptionBuilder().evalError("propertyMustBeConst", name.toString()).build();
      }
    }
    return property;
  }

  protected DirectCallNode getCallNode(ObjectMember property) {
    if (callNode == null) {
      CompilerDirectives.transferToInterpreterAndInvalidate();
      callNode = DirectCallNode.create(property.getCallTarget());
      insert(callNode);
    }
    assert callNode != null;
    return callNode;
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Declare the referenced property as `const` (e.g. `const x = ...`).
2. Inline the value into the const property if const-ness of the helper is undesirable.
3. Remove the `const` modifier from the referencing property if const-ness is not required.

Example fix

// before
const a = b // b is not const
b = 1
// after
const a = b
const b = 1

// Pkl
const b = 1
const a = b // b must be const for a to be const

When it happens

Trigger: Referencing a non-const local property from within another property declared `const`, or wherever const-ness is required (e.g. in default values consumed by tooling that must be constant-foldable).

Common situations: Building shared config values referenced from `const` properties; introducing a helper property that a const definition starts depending on after refactoring.

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

• externalMemberCannotHaveBody
• missingLocalPropertyValue
• objectCannotHaveProperty
• objectCannotHaveProperty
• methodMustBeConst

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