{"record":{"id":"240bf41e8a9fdf90","repo":"apple/pkl","slug":"elementindexoutofrange-240bf4","errorCode":"elementIndexOutOfRange","errorMessage":"Element index `{0}` is out of range `{1}`..`{2}`.","messagePattern":"Element index `(.+?)` is out of range `(.+?)`\\.\\.`(.+?)`\\.","errorType":"exception","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorEntryNode.java","lineNumber":104,"sourceCode":"    data.addMember(frame, key, member, this);\n  }\n\n  private void addListingEntry(VirtualFrame frame, ObjectData data, int parentLength) {\n    long index;\n    try {\n      index = keyNode.executeInt(frame);\n    } catch (UnexpectedResultException e) {\n      CompilerDirectives.transferToInterpreter();\n      throw exceptionBuilder()\n          .evalError(\"wrongListingKeyType\", new ProgramValue(\"\", VmUtils.getClass(e.getResult())))\n          .withLocation(keyNode)\n          .build();\n    }\n\n    // use same error messages as in checkIsValidListingAmendment and checkMaxListingMemberIndex\n    if (index < 0 || index >= parentLength) {\n      CompilerDirectives.transferToInterpreter();\n      throw exceptionBuilder()\n          .evalError(\"elementIndexOutOfRange\", index, 0, parentLength - 1)\n          .withLocation(keyNode)\n          .build();\n    }\n\n    data.addMember(frame, index, member, this);\n  }\n}\n","sourceCodeStart":86,"sourceCodeEnd":113,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/expression/generator/GeneratorEntryNode.java#L86-L113","documentation":"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.","triggerScenarios":"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.","commonSituations":"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`.","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."],"exampleFix":"// before\nlisting {\n  for (i in 0..4) {\n    [i + 1] { name = \"item \\(i)\" } // out of range on last iteration\n  }\n}\n// after\nlisting {\n  for (i in 0..4) {\n    [i] { name = \"item \\(i)\" }\n  }\n}","handlingStrategy":"validation","validationCode":"// Pkl guard before assigning an explicit listing index\nassert(index >= 0 && index < parentLength,\n    \"index \\(index) must be within 0..\\(parentLength - 1)\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["pkl","listing","index-out-of-range","generator"],"backgroundTag":"index-out-of-range","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}