apache/druid · error · SegmentLoadingException

Location[%s] with available bytes[%,d] cannot reserve segmen

Error message

Location[%s] with available bytes[%,d] cannot reserve segment[%s] of size[%,d] during bootstrap; check druid.segmentCache.locations maxSize

What it means

Thrown by reserveCompleteForBootstrap when an on-disk complete segment exists but location.addWeakReservationHold returns null because the location's available bytes are less than the segment size. Bootstrap previously mounted such segments unreserved (under-counting disk usage); it now fails fast and directs the operator at druid.segmentCache.locations maxSize.

Source

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

  private StorageLocation.ReservationHold<SegmentCacheEntry> reserveCompleteForBootstrap(
      DataSegment dataSegment,
      SegmentCacheEntryIdentifier id
  ) throws SegmentLoadingException
  {
    if (isRegisteredAtAnyLocation(id)) {
      return null;
    }
    for (StorageLocation location : locations) {
      final CacheEntry cacheEntry = new CompleteSegmentCacheEntry(dataSegment);
      if (!((CompleteSegmentCacheEntry) cacheEntry).checkExists(location.getPath())) {
        continue;
      }
      final StorageLocation.ReservationHold<SegmentCacheEntry> hold = location.addWeakReservationHold(
          id,
          () -> new CompleteSegmentCacheEntry(dataSegment)
      );
      if (hold == null) {
        throw new SegmentLoadingException(
            "Location[%s] with available bytes[%,d] cannot reserve segment[%s] of size[%,d] during bootstrap; check "
            + "druid.segmentCache.locations maxSize",
            location.getPath(),
            location.availableSizeBytes(),
            dataSegment.getId(),
            dataSegment.getSize()
        );
      }
      return hold;
    }
    return null;
  }

  /**
   * Reapply the persisted partial-load rule to a bootstrap-restored metadata entry. Reads the wrapper from the
   * segment's info-file {@code loadSpec}, resolves the selected bundle names against the just-parsed on-disk
   * metadata header, calls {@link PartialSegmentMetadataCacheEntry#applyRule}, then drives eager downloads for any
   * selected bundle that wasn't restored from disk (via {@link #awaitEagerDownloadsOrClearRule}). On failure the

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Raise druid.segmentCache.locations maxSize to at least the total size of existing cached segments.
2. Alternatively clear the cache directory so on-disk content fits the configured maxSize and re-downloads.
3. Verify location.freeSizeBytes/available bytes accounting; delete stale segment info files if accounting is corrupted.
4. Ensure the sum of segment sizes on disk matches what the location tracker expects after unclean shutdowns.

Example fix

// before: maxSize smaller than existing cache
druid.segmentCache.locations=[{"path":"/var/druid/segment-cache","maxSize":5000000000}]
// after
druid.segmentCache.locations=[{"path":"/var/druid/segment-cache","maxSize":100000000000}]

// pre-start check: sum of existing segment files must fit under maxSize
long used = duCacheDir(cachePath);
if (used > maxSize) { throw new IllegalStateException("Increase druid.segmentCache.locations maxSize to >= " + used); }

When it happens

Trigger: During bootstrap, a complete segment directory exists on a location whose availableSizeBytes is smaller than dataSegment.getSize(), so addWeakReservationHold cannot admit it.

Common situations: maxSize configured lower than the data already present in the cache directory (config reduced after cache grew); miscounting after crash/restart; shared or resized volumes.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Failed to reserve partial metadata for segment[%s] on locati
• No usable range reader for partial segment[%s]; its local la
• druid.segmentCache.locations must be set on historicals.
• Failed to write partial info file for segment[%s]
• Failed to load segment[%s] in all locations.

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