What causes "Element index `{0}` is out of range `{1}`..`{2}`." in apple/pkl?

Use `[length]` (append) instead of `[length + 1]` or another oversized explicit index when adding entries to a Listing.

apple/pkl · error · VmException

elementIndexOutOfRange

elementIndexOutOfRange

Error message

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

What it means

Thrown when a generator (e.g. `for` or an object amendment over a Listing) emits a listing entry at an index that does not exist in the parent Listing. Pkl uses the same messages as `checkIsValidListingAmendment`/`checkMaxListingMemberIndex`: valid indices are `0..parentLength-1`. Negative indices or indices past the end are rejected.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorEntryNode.java:104

    data.addMember(frame, key, member, this);
  }

  private void addListingEntry(VirtualFrame frame, ObjectData data, int parentLength) {
    long index;
    try {
      index = keyNode.executeInt(frame);
    } catch (UnexpectedResultException e) {
      CompilerDirectives.transferToInterpreter();
      throw exceptionBuilder()
          .evalError("wrongListingKeyType", new ProgramValue("", VmUtils.getClass(e.getResult())))
          .withLocation(keyNode)
          .build();
    }

    // use same error messages as in checkIsValidListingAmendment and checkMaxListingMemberIndex
    if (index < 0 || index >= parentLength) {
      CompilerDirectives.transferToInterpreter();
      throw exceptionBuilder()
          .evalError("elementIndexOutOfRange", index, 0, parentLength - 1)
          .withLocation(keyNode)
          .build();
    }

    data.addMember(frame, index, member, this);
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

Use `[length]` (append) instead of `[length + 1]` or another oversized explicit index when adding entries to a Listing.
Verify the index expression is in range `0..parentLength - 1` before assigning; clamp or compute from `parent.length`.
If appending, omit the key entirely (`_ { ... }`) rather than hardcoding an index.

Example fix

// before
listing {
  for (i in 0..4) {
    [i + 1] { name = "item \(i)" } // out of range on last iteration
  }
}
// after
listing {
  for (i in 0..4) {
    [i] { name = "item \(i)" }
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// Pkl guard before assigning an explicit listing index
assert(index >= 0 && index < parentLength,
    "index \(index) must be within 0..\(parentLength - 1)")

Prevention

Prefer `_ { ... }` append syntax over explicit indices when adding entries.
Derive indices from `parent.length` / the loop variable, never from hardcoded counts.
Use `[length]` for appending at the end of a Listing.

When it happens

Trigger: Inside a `for (x in parent)` or `... * ...` amendment body, an explicit list element key (e.g. `[index]`) evaluates to a value below 0 or >= the parent Listing's current length. Raised in `addListingEntry` during evalListing/evalListingClass.

Common situations: Writing `[5] = value` in a Listing amendment with fewer than 5 elements; computing an index from data (e.g. `this.length`) where the computed value overshoots; off-by-one errors using `count` instead of `count - 1`.

Related errors

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