{"record":{"id":"942755736ba33190","repo":"apple/pkl","slug":"elementindexoutofrange","errorCode":"elementIndexOutOfRange","errorMessage":"elementIndexOutOfRange ${index} 0 ${max}","messagePattern":"elementIndexOutOfRange (.+?) 0 (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/expression/binary/SubscriptNode.java","lineNumber":63,"sourceCode":"              \"charIndexOutOfRange\", index, 0, receiver.codePointCount(0, receiver.length()) - 1)\n          .withSourceSection(getRightNode().getSourceSection())\n          .withProgramValue(\"String\", receiver)\n          .build();\n    }\n\n    if (Character.isHighSurrogate(receiver.charAt(charIndex))\n        && charIndex < receiver.length() - 1\n        && Character.isLowSurrogate(receiver.charAt(charIndex + 1))) {\n      return receiver.substring(charIndex, charIndex + 2);\n    }\n    return receiver.substring(charIndex, charIndex + 1);\n  }\n\n  @Specialization\n  protected Object eval(VmList receiver, long index) {\n    if (index < 0 || index >= receiver.getLength()) {\n      CompilerDirectives.transferToInterpreter();\n      throw exceptionBuilder()\n          .evalError(\"elementIndexOutOfRange\", index, 0, receiver.getLength() - 1)\n          .withProgramValue(\"Collection\", receiver)\n          .build();\n    }\n    return receiver.get(index);\n  }\n\n  @Specialization\n  protected Object eval(VmMap receiver, Object key) {\n    var result = receiver.getOrNull(key);\n    if (result != null) return result;\n\n    CompilerDirectives.transferToInterpreter();\n    throw exceptionBuilder().cannotFindKey(receiver, key).build();\n  }\n\n  @Specialization\n  protected Object eval(","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/expression/binary/SubscriptNode.java#L45-L81","documentation":"Indexing a List with `[i]` outside the valid range 0..length-1 throws `elementIndexOutOfRange`, displaying the requested index and the maximum valid index. Pkl lists are fixed-size, so there is no auto-growth or negative wraparound.","triggerScenarios":"`list[index]` with index < 0 or index >= list.length, e.g. `servers[servers.length]` (off-by-one) on an empty or short list.","commonSituations":"Off-by-one in loops, assuming a list is non-empty, or deriving indices from external config that doesn't match list size.","solutions":["Validate `index >= 0 && index < list.length` before subscripting","Use `list.elementAtOrNull(index)` if available, or guard with `list.isEmpty()`","Fix the index computation (length vs length-1)"],"exampleFix":"// before (Pkl)\nval last = items[items.length]\n// after\nval last = items[items.length - 1]","handlingStrategy":"validation","validationCode":"function safeListGet(list, i) {\n  return Array.isArray(list) && Number.isInteger(i) && i >= 0 && i < list.length ? list[i] : null;\n}","typeGuard":"const inListBounds = (list, i) => Array.isArray(list) && i >= 0 && i < list.length;","tryCatchPattern":null,"preventionTips":["Use length - 1 for last element, not length","Check non-emptiness before positional access","Validate externally-supplied indices against list length"],"tags":["list","index-out-of-range","pkl"],"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"}