What causes "RuntimeException wrapping underlying cause" in apache/druid?

Read the wrapped cause via getCause() to find the zip or upload failure

apache/druid · error · RuntimeException

RuntimeException wrapping underlying cause

Error message

RuntimeException wrapping underlying cause

What it means

AzureDataSegmentPusher.pushToPath wraps any exception during segment zip creation or upload in a plain RuntimeException. This is a catch-all so callers of push() see a non-checked failure with the original cause attached, e.g. from CompressionUtils.zip or uploadDataSegment.

Source

Thrown at extensions-core/azure-extensions/src/main/java/org/apache/druid/storage/azure/AzureDataSegmentPusher.java:114

  {
    String prefix = segmentConfig.getPrefix();
    boolean prefixIsNullOrEmpty = org.apache.commons.lang3.StringUtils.isEmpty(prefix);
    final String azurePath = JOINER.join(
        prefixIsNullOrEmpty ? null : StringUtils.maybeRemoveTrailingSlash(prefix),
        storageDirSuffix
    );

    final int binaryVersion = SegmentUtils.getVersionFromDir(indexFilesDir);
    File zipOutFile = null;

    try {
      final File outFile = zipOutFile = Files.createTempFile("index", ".zip").toFile();
      final long size = CompressionUtils.zip(indexFilesDir, zipOutFile);

      return uploadDataSegment(segment, binaryVersion, size, outFile, azurePath);
    }
    catch (Exception e) {
      throw new RuntimeException(e);
    }
    finally {
      if (zipOutFile != null) {
        log.info("Deleting zipped index File[%s]", zipOutFile);
        zipOutFile.delete();
      }
    }
  }

  @Override
  public Map<String, Object> makeLoadSpec(URI uri)
  {
    return makeLoadSpec(uri.toString());
  }

  @VisibleForTesting
  String getAzurePath(final DataSegment segment, final boolean useUniquePath)
  {

View on GitHub (pinned to 9b90983fd2)

Solutions

Read the wrapped cause via getCause() to find the zip or upload failure
Ensure enough free disk space in the temp directory for segment zips
Verify Azure credentials and that the segment size is within Azure blob limits
Retry the push; transient Azure errors are common during heavy ingestion

Example fix

// before
catch (Exception e) {
  throw new RuntimeException(e);
}
// after
catch (Exception e) {
  throw new RuntimeException("Failed to push segment " + segment.getId() + " to " + azurePath, e);
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (new File(System.getProperty("java.io.tmpdir")).getUsableSpace() < minRequiredBytes) throw new IllegalStateException("Insufficient temp space for segment zip");

Try / catch

try { pusher.push(segmentFiles, segment); } catch (RuntimeException e) { log.error("Segment push failed: %s", e.getCause(), e); throw e; }

Prevention

Monitor temp disk space on ingestion nodes
Validate Azure credentials and blob size limits before large segment pushes
Retry pushes on transient Azure errors with backoff
Include segment id/path in wrapped messages for debuggability

When it happens

Trigger: pushToPath fails while creating the temp zip file, zipping the index directory (IOException from disk), or uploading via uploadDataSegment (Azure auth/network/size errors).

Common situations: Insufficient local temp disk space when zipping; Azure upload failures (throttling, oversized blob, bad credentials) during segment publishing.

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/0850df08df6e118b. Report an issue: GitHub.