apple/pkl · error · VmException

propertyMustBeConst

propertyMustBeConst

Error message

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

What it means

In Pkl, `const` properties can only be read from within const-qualified contexts (e.g. `fixed`/`const` members or definitions). ReadPropertyNode.checkConst runs when a property read site requires const-ness and verifies that the resolved class property (and the object member) actually declares `const`. If the resolved property is not `const`, the evaluator refuses the reference with propertyMustBeConst rather than allowing a value that could differ between amending objects.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/member/ReadPropertyNode.java:169

  private VmException cannotFindProperty(VmObjectLike receiver) {
    return exceptionBuilder()
        .cannotFindProperty(
            receiver, propertyName, true, lookupMode != MemberLookupMode.EXPLICIT_RECEIVER)
        .build();
  }

  // Only ever need to check once per node because `needsConst` is only true in the case of:
  //
  // * implicit receiver in class (and module) bodies
  // * `local const` object members
  //
  // and the const-ness of a resolved property cannot be changed by subclasses / amending objects.
  private void checkConst(VmObjectLike receiver) {
    if (needsConst && !isConstChecked) {
      CompilerDirectives.transferToInterpreterAndInvalidate();
      var property = receiver.getVmClass().getProperty(propertyName);
      if (property != null && !property.isConst()) {
        throw exceptionBuilder().evalError("propertyMustBeConst", propertyName.toString()).build();
      }
      var objectMember = receiver.getMember(propertyName);
      if (objectMember != null && !objectMember.isConst()) {
        throw exceptionBuilder().evalError("propertyMustBeConst", propertyName.toString()).build();
      }
      if (property == null && objectMember == null) {
        // fall through; `cannotFindProperty` gets thrown when we attempt to read the property.
        return;
      }
      isConstChecked = true;
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

Declare the referenced property as `const` (e.g. change `bar: Int` to `const bar: Int`) in the defining class or object
Replace the non-const read with a literal or expression that only involves const/literal values
Change the reading property from `const`/`fixed` to a regular property so const-ness is not required
If the property is conditionally missing, verify the property exists on the receiver (checkConst falls through to cannotFindProperty otherwise)

Example fix

// before
class Server {
  port: Int = 8080
  const defaultPort: Int = port // ERROR: port is not const
}
// after
class Server {
  const port: Int = 8080
  const defaultPort: Int = port
}

Defensive patterns

Strategy: validation

Validate before calling

// pkl: check the referenced property is declared const before using it in a const context
// class C { const p: Int = q }  ->  ensure class C declares: const q ...
function isConstProp(cls: Class, name: String): Boolean =
  cls.getProperty(name).isConst

Type guard

null

Try / catch

null

Prevention

Mark values intended for const consumption as `const` at definition time
Avoid reading regular properties from `fixed`/`const` members
Run `pkl eval` in CI to catch const violations before publishing schemas

When it happens

Trigger: Reading a non-const property from a context marked needsConst: e.g. referencing an object property inside a `const` property definition, inside a `fixed` member, or in another location whose read node was constructed with needsConst=true (evalObject path).

Common situations: Declaring `const x: Int = foo.bar` where `bar` is a normal (non-const) property; referencing a parent object's mutable property from a `fixed` property; copying an example from `fixed`/`const` docs against a property that was later de-const-ed.

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

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