apple/pkl · error

undefinedPropertyValue

undefinedPropertyValue

Error message

undefinedPropertyValue

What it means

Pkl throws undefinedPropertyValue when a property's value is evaluated but no concrete value exists: the property has no body/expression and its type (or enclosing class/module) supplies no default value. DefaultPropertyBodyNode.executeGeneric first tries the type node's default; when that is null it raises undefinedPropertyValue naming the property and receiver. In effect, the property is declared but never assigned anything Pkl can compute.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/member/DefaultPropertyBodyNode.java:53

      SourceSection sourceSection, Identifier propertyName, @Nullable PropertyTypeNode typeNode) {
    super(sourceSection);
    this.propertyName = propertyName;
    this.typeNode = typeNode;
  }

  public boolean isUndefined(VirtualFrame frame) {
    return typeNode == null || typeNode.getDefaultValue(frame) == null;
  }

  @Override
  public Object executeGeneric(VirtualFrame frame) {
    if (typeNode != null) {
      var defaultValue = typeNode.getDefaultValue(frame);
      if (defaultValue != null) return defaultValue;
    }

    CompilerDirectives.transferToInterpreter();
    throw exceptionBuilder()
        .undefinedPropertyValue(propertyName, VmUtils.getReceiver(frame))
        .build();
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Assign a concrete value to the named property at the reported location.
2. Provide a default in the class/module (`port: Int = 8080`) so instances inherit it.
3. Set the property in the `new` expression or the extending module.
4. If the property must stay unset for now, guard readers with `x?.property != null` checks before use.

Example fix

// before
server {
  port: Int  // no value, no default
}

// after
server {
  port: Int = 8080
}

// Before consuming a rendered config, check required properties are defined:
// e.g. in a test:
// if (config.port == null) throw "port is not set"
// Or in Pkl itself: `port: Int = 8080` provides a default.

When it happens

Trigger: Accessing a property declared with a type but no value (e.g. `port: Int`) whose type has no default; a parent class/module property left undefined and not overridden; evaluating a listing/mapping element slot never filled; a required property omitted in an `new` expression without a default.

Common situations: Config consumers reading a field the author assumed someone else would set; new Pkl users writing type-only declarations expecting implicit defaults; a base template leaving properties abstract and the child forgetting to define them; removing a default from a type during refactoring.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• externalMemberCannotHaveBody
• missingLocalPropertyValue
• objectCannotHaveProperty
• objectCannotHaveProperty
• propertyMustBeConst

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