{"record":{"id":"d8827199bf3e5339","repo":"apple/pkl","slug":"elementindexoutofrange-d88271","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/literal/SpecializedObjectLiteralNode.java","lineNumber":212,"sourceCode":"\n    checkedIsValidMappingAmendment = true;\n    return true;\n  }\n\n  @Idempotent\n  protected final boolean checkMaxListingMemberIndex(int parentLength) {\n    assert maxListingMemberIndex != Long.MIN_VALUE;\n    if (maxListingMemberIndex < parentLength) return true;\n\n    CompilerDirectives.transferToInterpreter();\n    var cursor = EconomicMaps.getEntries(members);\n    while (cursor.advance()) {\n      var key = cursor.getKey();\n      if (!(key instanceof Long)) continue;\n\n      var index = (long) key;\n      if (index < 0 || index >= parentLength) {\n        throw exceptionBuilder()\n            .evalError(\"elementIndexOutOfRange\", index, 0, parentLength - 1)\n            .withSourceSection(cursor.getValue().getHeaderSection())\n            .build();\n      }\n    }\n\n    throw exceptionBuilder().unreachableCode().build();\n  }\n\n  @ExplodeLoop\n  protected void addListEntries(\n      VirtualFrame frame,\n      int parentLength,\n      EconomicMap<Object, ObjectMember> result,\n      ExpressionNode[] keyNodes,\n      ObjectMember[] values) {\n\n    for (var i = 0; i < keyNodes.length; i++) {","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/expression/literal/SpecializedObjectLiteralNode.java#L194-L230","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Use indices within `0..parentLength-1`, adjusting the amendment to only overwrite existing elements","If you need to append, extend via a computed new Listing (`[...parent, newItem]` style) or define the fuller list where it is created","Re-check the parent list's length after version upgrades and regenerate indices"],"exampleFix":"// before: parent has 3 elements (indices 0..2)\nitems { [3] = 4 }\n// after\nitems { [2] = 4 } // overwrite an existing element\n","handlingStrategy":"validation","validationCode":"// Before amending a Listing, check parent length:\n// amendment indices must satisfy: index >= 0 && index < parentItems.length\n","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Re-derive indices after any upstream list change","Never 'append' via amendment — overwrite only, or build a new list","Remember indices are 0-based"],"tags":["pkl","listing","index-out-of-range","amends"],"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"}