{"record":{"id":"2b616bfa725c701b","repo":"apache/beam","slug":"position-s-was-out-of-bounds-for-ranges-s","errorCode":null,"errorMessage":"Position %s was out of bounds for ranges %s.","messagePattern":"Position (.+?) was out of bounds for ranges (.+?)\\.","errorType":"exception","errorClass":"IndexOutOfBoundsException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java","lineNumber":991,"sourceCode":"  @VisibleForTesting\n  static int computeTotalNumElements(\n      Map<OffsetRange, Integer> nonOverlappingRangesToNumElementsPerPosition) {\n    long sum = 0;\n    for (Map.Entry<OffsetRange, Integer> range :\n        nonOverlappingRangesToNumElementsPerPosition.entrySet()) {\n      sum +=\n          Math.multiplyExact(\n              Math.subtractExact(range.getKey().getTo(), range.getKey().getFrom()),\n              range.getValue());\n    }\n    return Ints.checkedCast(sum);\n  }\n\n  @VisibleForTesting\n  static KV<Long, Integer> computePositionForIndex(\n      Map<OffsetRange, Integer> nonOverlappingRangesToNumElementsPerPosition, int index) {\n    if (index < 0) {\n      throw new IndexOutOfBoundsException(\n          String.format(\n              \"Position %s was out of bounds for ranges %s.\",\n              index, nonOverlappingRangesToNumElementsPerPosition));\n    }\n    for (Map.Entry<OffsetRange, Integer> range :\n        nonOverlappingRangesToNumElementsPerPosition.entrySet()) {\n      int numElementsInRange =\n          Ints.checkedCast(\n              Math.multiplyExact(\n                  Math.subtractExact(range.getKey().getTo(), range.getKey().getFrom()),\n                  range.getValue()));\n      if (numElementsInRange <= index) {\n        index -= numElementsInRange;\n        continue;\n      }\n      long position = range.getKey().getFrom() + index / range.getValue();\n      int subPosition = index % range.getValue();\n      return KV.of(position, subPosition);","sourceCodeStart":973,"sourceCodeEnd":1009,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java#L973-L1009","documentation":"PCollectionViews.computePositionForIndex maps a global list index onto the materialized iterable view's offset ranges. A negative index (or one not covered by any range, surfacing later) throws IndexOutOfBoundsException 'Position %s was out of bounds for ranges %s.' This is a defensive bounds check used in testing the iterable-view position computation; it should be unreachable through normal pipeline use and indicates an out-of-range lookup.","triggerScenarios":"Calling computePositionForIndex (a @VisibleForTesting static helper) with a negative index, or via iterable view materialization paths where an index lookup falls outside all OffsetRange buckets of the view.","commonSituations":"Unit tests exercising PCollectionViews iterable-view internals with hand-computed indices; runner-side iterable-view random-access where the materialization ranges and the requested index disagree (runner/SDK mismatch or corrupted view metadata).","solutions":["Clamp/validate the index before calling computePositionForIndex: only pass indices within [0, totalElements).","If hit through view access, verify the iterable view materialization ranges match the data (re-run with matching SDK/runner versions).","For tests, compute the expected index from the same OffsetRange map rather than hardcoding it.","Report to Beam if a legitimate in-range index triggers this via View.asList() access — likely a runner bug."],"exampleFix":"// before\nKV<Long, Integer> pos = PCollectionViews.computePositionForIndex(ranges, index);\n// after\nif (index < 0 || index >= totalElements) throw new IllegalArgumentException(\"index \" + index + \" out of range\");\nKV<Long, Integer> pos = PCollectionViews.computePositionForIndex(ranges, index);","handlingStrategy":"validation","validationCode":"if (index < 0 || index >= totalElements) {\n  throw new IllegalArgumentException(\"index out of range: \" + index);\n}\nKV<Long, Integer> pos = PCollectionViews.computePositionForIndex(ranges, index);","typeGuard":null,"tryCatchPattern":"try {\n  KV<Long, Integer> pos = PCollectionViews.computePositionForIndex(ranges, index);\n} catch (IndexOutOfBoundsException e) {\n  /* clamp index or recompute ranges */\n}","preventionTips":["Only pass indices derived from the same range map, never hand-computed constants.","Keep runner and SDK versions aligned so iterable-view metadata matches access patterns.","In tests, assert index bounds before invoking this VisibleForTesting helper."],"tags":["java","apache-beam","bounds-check","index-out-of-bounds"],"backgroundTag":"index-out-of-bounds","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}