apache/druid · error · SegmentLoadingException

Failed to mount partial metadata for segment[%s]

Error message

Failed to mount partial metadata for segment[%s]

What it means

After reserving a location and writing the partial info file, SegmentLocalCacheManager mounts the PartialSegmentMetadataCacheEntry at the location. An IOException during mount (file materialization, mapping, or file-locking failure) is wrapped in this SegmentLoadingException.

Source

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

          final PartialSegmentMetadataCacheEntry metadata = reserved.metadata();
          // findOrReservePartial only invokes reservePartial (which writes the info file) on the fresh-reserve
          // branch. On the find-existing branch the info file on disk still carries the PRIOR rule's wrapped
          // load spec, so a rule swap here would apply in memory only. Rewrite unconditionally before mount.
          try {
            rewriteInfoFile(dataSegment);
          }
          catch (IOException e) {
            throw new SegmentLoadingException(
                e,
                "Failed to write partial info file for segment[%s]",
                dataSegment.getId()
            );
          }
          try {
            metadata.mount(reserved.location());
          }
          catch (IOException e) {
            throw new SegmentLoadingException(
                e,
                "Failed to mount partial metadata for segment[%s]",
                dataSegment.getId()
            );
          }
          final PartialSegmentFileMapperV10 mapper = metadata.getFileMapper();
          if (mapper == null) {
            throw DruidException.defensive(
                "Partial metadata for segment[%s] mounted without a file mapper",
                dataSegment.getId()
            );
          }
          // Register the info-file cleanup hook BEFORE anything that could throw. Any throw between mount and
          // awaitEagerDownloadsOrClearRule leaves the metadata entry weak-reserved with the hook attached; when
          // cache eventually reclaims, the info file gets deleted along with the entry.
          metadata.setOnUnmount(() -> deleteSegmentInfoFile(dataSegment));
          final Set<String> selected = Set.copyOf(
              wrapper.getSelectedBundleNames(dataSegment, mapper.getSegmentFileMetadata())

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Check the wrapped IOException cause for the root disk/permission problem on the cache location.
2. Verify the cache location directories exist, are writable, and have free space.
3. Retry the load after resolving disk issues; the coordinator load queue will re-attempt.
4. Check logs for concurrent eviction/load races on the same segment id and location.

final File loc = reserved.location().getPath();
if (!loc.exists() || !loc.canWrite() || loc.getUsableSpace() < MIN_FREE_BYTES) {
  throw new IllegalStateException("Cache location unusable for mount: " + loc);
}

try {
  cacheManager.loadPartial(segment, rule);
} catch (SegmentLoadingException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Failed to mount partial metadata")) {
    retryWithBackoff(e); // transient disk/IO issues often resolve on retry
  } else {
    throw e;
  }
}

When it happens

Trigger: metadata.mount(reserved.location()) throws IOException during the partial-load load path — e.g. failure creating files/directories or acquiring the mount at the reserved cache location.

Common situations: Cache location disk full or failing; concurrent load/eviction race corrupting the mount state; permissions problems on the cache directory; underlying storage of the partial files unavailable.

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

• Exception while writing distribution file for interval [%s],
• Failed to write to file: %s. Current size of file: %d
• Failed to write to file: %s. Current size of file: %d
• Failed to write partial info file for segment[%s]
• Failed to rewrite info file for segment[%s] while releasing

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