apache/druid · error · SegmentLoadingException

Failed to open range reader for segment[%s]

Error message

Failed to open range reader for segment[%s]

What it means

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.

Source

Thrown at server/src/main/java/org/apache/druid/segment/loading/SegmentLocalCacheManager.java:1295

  /**
   * Open a range reader for the segment's deep storage via the wrapper's {@link PartialLoadSpec#openRangeReader}
   * (which delegates to the inner load spec), wrapping any {@link IOException} as a {@link SegmentLoadingException}.
   * Returns {@code null} if the backend doesn't support range reads.
   */
  @Nullable
  private SegmentRangeReader openPartialRangeReader(DataSegment dataSegment, PartialLoadSpec wrapper)
      throws SegmentLoadingException
  {
    try {
      final SegmentRangeReader rangeReader = wrapper.openRangeReader();
      if (rangeReader == null) {
        return null;
      }
      // Bound concurrent deep-storage reads at the actual range-read (see PermitLimitedSegmentRangeReader).
      return new PermitLimitedSegmentRangeReader(rangeReader, virtualStorageLoadingThreadPool);
    }
    catch (IOException e) {
      throw new SegmentLoadingException(e, "Failed to open range reader for segment[%s]", dataSegment.getId());
    }
  }

  /**
   * The fingerprint of the currently-applied partial-load rule for {@code segmentId}, or {@code null} if no rule is
   * currently applied (or the segment has no partial metadata entry (e.g. it was eager-loaded as a complete cache
   * entry). Test-only. Delegates to {@link PartialSegmentMetadataCacheEntry#getRuleFingerprint} on the segment's
   * cache entry.
   */
  @VisibleForTesting
  @Nullable
  String getRuleFingerprintForSegment(SegmentId segmentId)
  {
    final SegmentCacheEntryIdentifier id = new SegmentCacheEntryIdentifier(segmentId);
    for (StorageLocation location : locations) {
      final CacheEntry entry = location.getCacheEntry(id);
      if (entry instanceof PartialSegmentMetadataCacheEntry partial) {
        return partial.getRuleFingerprint();

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Check the wrapped IOException cause for the root open failure (404, connection, permissions).
2. Verify the segment's loadSpec location still exists in deep storage.
3. Fix deep-storage connectivity/credentials, or re-run ingestion if the segment files are genuinely lost.
4. If it happened after a deep-storage migration, update segment metadata loadSpecs to the new location.

// before opening a range reader, confirm the segment location exists
if (!deepStorage.segmentExists(segment)) {
  throw new IllegalStateException("Segment missing from deep storage: " + segment.getId());
}

try {
  final SegmentRangeReader reader = cacheManager.makeRangeReader(segment);
} catch (SegmentLoadingException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Failed to open range reader")) {
    alertAndFallBack(e); // e.g. fall back to full segment load or fail the query cleanly
  } else {
    throw e;
  }
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• Could not fetch last modified timestamp from URI [%s]
• Error occurred while trying to read uri:
• Failed eager download of rule-selected bundles for segment[%
• No usable range reader for partial segment[%s]; its local la
• Error reading response

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/c4f68849f14d451a. Report an issue: GitHub.