apache/druid · error · SegmentLoadingException

Failed eager download of rule-selected bundles for segment

Error message

Failed eager download of rule-selected bundles for segment[%s]; cleared partial-load rule

What it means

When eager-downloading rule-selected bundles for a partial-load segment, SegmentLocalCacheManager collects failures across the download pool. On the first failure it clears the applied partial-load rule (so late successes are not held) and throws this SegmentLoadingException describing the segment and failure.

Solutions

1. Inspect firstFailure (the wrapped cause) for the underlying download error and fix it (network, credentials, deep-storage health).
2. Verify the partial-load rule selects valid, existing bundles in deep storage.
3. Retry the load; ensure retries/backoff on deep-storage access are configured sensibly.
4. Check deep-storage credentials and bucket/container configuration (e.g. druid.s3.accessKey, endpoint settings).

// pre-flight: verify rule-selected bundles exist in deep storage before eager download
for (final String bundle : ruleSelectedBundleNames) {
  if (!deepStorage.objectExists(bucket, bundle)) {
    throw new IllegalStateException("Rule-selected bundle missing in deep storage: " + bundle);
  }
}

try {
  cacheManager.loadPartial(segment, rule);
} catch (SegmentLoadingException e) {
  if (e.getMessage() != null && e.getMessage().contains("Failed eager download")) {
    retryWithBackoff(e); // deep-storage/network transients; rule was cleared, so re-apply cleanly
  } else {
    throw e;
  }
}

When it happens

Trigger: Eager bundle download for a segment's partial-load rule fails — deep-storage fetch errors (S3/HTTP timeouts, 404/403), pool task exceptions, or network interruptions — leaving firstFailure non-null.

Common situations: Deep storage briefly unavailable or throttled; misconfigured rule selecting bundles that don't exist; network flakiness between historical and deep storage; credentials expiring mid-download.

Related errors

• Failed to open range reader for segment
• Call returned null IP for
• Could not fetch last modified timestamp from URI
• Could not find remote outputs of stage
• Couldn't delete segments from Azure. See the task logs for…

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

Appendix: source

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

        // Signal cancel WITHOUT interrupt — see cancel(false) comment above; interrupting mid-NIO closes the
        // shared mapper FD.
        f.cancel(false);
      }
      catch (ExecutionException e) {
        firstFailure = e.getCause() != null ? e.getCause() : e;
      }
      catch (CancellationException e) {
        // Defensive: shouldn't reach here on the first-failure branch (we only cancel after firstFailure is set),
        // but if it does, treat it uniformly.
        firstFailure = e;
      }
    }

    if (firstFailure != null) {
      // Any late-completing pool task that still succeeds after we've cleared the rule will call registerBundle →
      // observing ruleSelectedBundleNames == {} and skipping the rule-hold acquire.
      metadata.clearRule();
      throw new SegmentLoadingException(
          firstFailure,
          "Failed eager download of rule-selected bundles for segment[%s]; cleared partial-load rule",
          dataSegment.getId()
      );
    }
  }

  /**
   * Materialize the segment's wrapped load spec to a {@link PartialLoadSpec}.
   */
  private PartialLoadSpec materializePartialLoadSpec(DataSegment dataSegment) throws SegmentLoadingException
  {
    final LoadSpec materializedLoadSpec;
    try {
      materializedLoadSpec = jsonMapper.convertValue(dataSegment.getLoadSpec(), LoadSpec.class);
    }
    catch (Exception e) {
      throw new SegmentLoadingException(

View on GitHub (pinned to 9b90983fd2)