{"record":{"id":"c4f68849f14d451a","repo":"apache/druid","slug":"failed-to-open-range-reader-for-segment-s","errorCode":null,"errorMessage":"Failed to open range reader for segment[%s]","messagePattern":"Failed to open range reader for segment\\[(.+?)\\]","errorType":"exception","errorClass":"SegmentLoadingException","httpStatus":null,"severity":"error","filePath":"server/src/main/java/org/apache/druid/segment/loading/SegmentLocalCacheManager.java","lineNumber":1295,"sourceCode":"  /**\n   * Open a range reader for the segment's deep storage via the wrapper's {@link PartialLoadSpec#openRangeReader}\n   * (which delegates to the inner load spec), wrapping any {@link IOException} as a {@link SegmentLoadingException}.\n   * Returns {@code null} if the backend doesn't support range reads.\n   */\n  @Nullable\n  private SegmentRangeReader openPartialRangeReader(DataSegment dataSegment, PartialLoadSpec wrapper)\n      throws SegmentLoadingException\n  {\n    try {\n      final SegmentRangeReader rangeReader = wrapper.openRangeReader();\n      if (rangeReader == null) {\n        return null;\n      }\n      // Bound concurrent deep-storage reads at the actual range-read (see PermitLimitedSegmentRangeReader).\n      return new PermitLimitedSegmentRangeReader(rangeReader, virtualStorageLoadingThreadPool);\n    }\n    catch (IOException e) {\n      throw new SegmentLoadingException(e, \"Failed to open range reader for segment[%s]\", dataSegment.getId());\n    }\n  }\n\n  /**\n   * The fingerprint of the currently-applied partial-load rule for {@code segmentId}, or {@code null} if no rule is\n   * currently applied (or the segment has no partial metadata entry (e.g. it was eager-loaded as a complete cache\n   * entry). Test-only. Delegates to {@link PartialSegmentMetadataCacheEntry#getRuleFingerprint} on the segment's\n   * cache entry.\n   */\n  @VisibleForTesting\n  @Nullable\n  String getRuleFingerprintForSegment(SegmentId segmentId)\n  {\n    final SegmentCacheEntryIdentifier id = new SegmentCacheEntryIdentifier(segmentId);\n    for (StorageLocation location : locations) {\n      final CacheEntry entry = location.getCacheEntry(id);\n      if (entry instanceof PartialSegmentMetadataCacheEntry partial) {\n        return partial.getRuleFingerprint();","sourceCodeStart":1277,"sourceCodeEnd":1313,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/server/src/main/java/org/apache/druid/segment/loading/SegmentLocalCacheManager.java#L1277-L1313","documentation":"To serve segments not fully in cache, SegmentLocalCacheManager wraps a deep-storage range reader in a PermitLimitedSegmentRangeReader. If opening the underlying range reader throws an IOException, it is wrapped in this SegmentLoadingException.","triggerScenarios":"Creating the segment range reader for a segment fails — the underlying deep-storage client cannot open the segment files (missing object, IO error, connection failure).","commonSituations":"Segment files deleted from deep storage while still referenced in metadata; deep-storage outage; bad loadSpec pointing at the wrong location after a storage migration; network/credentials issues.","solutions":["Check the wrapped IOException cause for the root open failure (404, connection, permissions).","Verify the segment's loadSpec location still exists in deep storage.","Fix deep-storage connectivity/credentials, or re-run ingestion if the segment files are genuinely lost.","If it happened after a deep-storage migration, update segment metadata loadSpecs to the new location."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// before opening a range reader, confirm the segment location exists\nif (!deepStorage.segmentExists(segment)) {\n  throw new IllegalStateException(\"Segment missing from deep storage: \" + segment.getId());\n}","typeGuard":null,"tryCatchPattern":"try {\n  final SegmentRangeReader reader = cacheManager.makeRangeReader(segment);\n} catch (SegmentLoadingException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to open range reader\")) {\n    alertAndFallBack(e); // e.g. fall back to full segment load or fail the query cleanly\n  } else {\n    throw e;\n  }\n}","preventionTips":["Keep segment metadata consistent with actual deep-storage contents.","Verify loadSpec locations after any deep-storage migration.","Configure deep-storage client timeouts/retries and monitor availability.","Alert on 404s from deep storage for segments still in the metadata store."],"tags":["io","deep-storage","range-reader","network"],"backgroundTag":"file-open-failed","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}