What causes "Failed to load segment[%s] in reserved location[%s]" in apache/druid?

Inspect the alert and the wrapped exception for the location-specific root cause (network vs disk vs segment corruption).

apache/druid · error · SegmentLoadingException

Failed to load segment[%s] in reserved location[%s]

Error message

Failed to load segment[%s] in reserved location[%s]

What it means

Thrown when loading a segment into a pre-reserved location fails after an alert is emitted ('Failed to load segment in current location [%s], try next location if any'). It marks the specific reserved location as failed for this segment; if other locations exist the load may be retried there.

Source

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

        } else if (isWeak) {
          mountLocation.trackWeakLoad(dataSegment.getSize());
        } else {
          mountLocation.trackStaticLoad(dataSegment.getSize());
        }

        if (config.isVirtualStorageEphemeral()) {
          setOnUnmount(() -> deleteSegmentInfoFile(dataSegment));
        }
      }
      catch (SegmentLoadingException e) {
        try {
          log.makeAlert(
              e,
              "Failed to load segment in current location [%s], try next location if any",
              location.getPath().getAbsolutePath()
          ).addData("location", location.getPath().getAbsolutePath()).emit();

          throw new SegmentLoadingException(
              "Failed to load segment[%s] in reserved location[%s]",
              dataSegment.getId(),
              location.getPath().getAbsolutePath()
          );
        }
        finally {
          unmount();
        }
      }
      catch (Throwable t) {
        unmount();
        throw t;
      }
      finally {
        CloseableUtils.closeAndSuppressExceptions(selfHold, e -> log.warn(e, "Failed to release mount hold[%s]", id));
      }
    }

View on GitHub (pinned to 9b90983fd2)

Solutions

Inspect the alert and the wrapped exception for the location-specific root cause (network vs disk vs segment corruption).
Ensure other cache locations are configured so the segment can fall to the next location; this error is retriable there.
Free space or fix disk health on the failing location path.
Retry the load; repeated failures on the same location indicate persistent hardware or permission problems.

Defensive patterns

Strategy: try-catch

Try / catch

try { loadIntoReservedLocation(segment, location); } catch (SegmentLoadingException e) { log.warn(e, "Will try next configured location"); }

Prevention

Configure at least two cache locations for per-location failover.
Keep reserved location disks healthy with free-space alerts.
Watch makeAlert events for repeated failures on the same location path.

When it happens

Trigger: loadInLocation on a reserved StorageLocation throws (download error, segment unpacking failure, IO error) while the segment was assigned to that location's hold.

Common situations: Transient deep-storage/network errors during download; disk full or IO errors on the reserved location; corrupted downloaded segment files causing index open failures.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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