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.

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)

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[%s]
• Failed to fetch Avro schema id[%s] from registry. Check if t
• Failed to get blob item from Azure container[%s], prefix[%s
• Couldn't delete segments from Azure. See the task logs for m
• e.getMessage()

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