apple/pkl · error · VmException

elementIndexOutOfRange

elementIndexOutOfRange

Error message

Element index `{0}` is out of range `{1}`..`{2}`.

What it means

When amending an existing Listing, amendment entries may only occupy indices that already exist in the parent Listing (amendments overwrite, they don't extend). `checkMaxListingMemberIndex` iterates the literal's Long keys and throws `elementIndexOutOfRange` when an index is negative or >= the parent Listing's length.

Source

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

    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();
      if (!(key instanceof Long)) continue;

      var index = (long) key;
      if (index < 0 || index >= parentLength) {
        throw exceptionBuilder()
            .evalError("elementIndexOutOfRange", index, 0, parentLength - 1)
            .withSourceSection(cursor.getValue().getHeaderSection())
            .build();
      }
    }

    throw exceptionBuilder().unreachableCode().build();
  }

  @ExplodeLoop
  protected void addListEntries(
      VirtualFrame frame,
      int parentLength,
      EconomicMap<Object, ObjectMember> result,
      ExpressionNode[] keyNodes,
      ObjectMember[] values) {

    for (var i = 0; i < keyNodes.length; i++) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Use indices within `0..parentLength-1`, adjusting the amendment to only overwrite existing elements
2. If you need to append, extend via a computed new Listing (`[...parent, newItem]` style) or define the fuller list where it is created
3. Re-check the parent list's length after version upgrades and regenerate indices

Example fix

// before: parent has 3 elements (indices 0..2)
items { [3] = 4 }
// after
items { [2] = 4 } // overwrite an existing element

// Before amending a Listing, check parent length:
// amendment indices must satisfy: index >= 0 && index < parentItems.length

When it happens

Trigger: Amending a Listing with fewer elements than the amendment's highest index, e.g. parent has 3 elements and the amendment writes `[3] = x`; using a negative index; guessing indices after upstream shrinks the default list.

Common situations: Overriding a dependency's default list that changed length between versions; hand-written indices that assume one-based numbering; appending to a Listing via amendment (not allowed — use `default` or `new` for extension).

Related errors

• elementIndexOutOfRange
• listingAmendmentCannotHaveParameters
• defaultMember/cannotFindMember
• expectedNonEmptyListing
• expectedSingleElementListing

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