apache/druid · error · IllegalStateException

Exception while writing distribution file for interval [%s],

Error message

Exception while writing distribution file for interval [%s], task [%s]

What it means

The dimension-distribution phase runner persists each sub-task's StringDistribution to a JSON file under the task's temp dir. If writing that file throws an IOException, the runner stops gracefully and rethrows ISE wrapping the original exception, naming the interval and sub-task.

Source

Thrown at indexing-service/src/main/java/org/apache/druid/indexing/common/task/batch/parallel/PartialDimensionDistributionParallelIndexTaskRunner.java:215

      String subTaskId,
      StringDistribution distribution
  )
  {
    try {
      File intervalDir = getIntervalDistributionDir(interval);
      FileUtils.mkdirp(intervalDir);

      File distributionJsonFile = getDistributionJsonFile(intervalDir, subTaskId);
      getToolbox().getJsonMapper().writeValue(distributionJsonFile, distribution);
    }
    catch (IOException e) {
      String errorMsg = StringUtils.format(
          "Exception while writing distribution file for interval [%s], task [%s]",
          interval,
          subTaskId
      );
      stopGracefully(errorMsg);
      throw new ISE(e, errorMsg);
    }
  }

  private StringDistribution readDistributionFromFile(File intervalDir, String subTaskId)
  {
    try {
      File distributionJsonFile = getDistributionJsonFile(intervalDir, subTaskId);
      return getToolbox().getJsonMapper().readValue(distributionJsonFile, StringDistribution.class);
    }
    catch (IOException e) {
      throw new ISE(e, "Error while reading distribution for interval [%s], task [%s]",
                    intervalDir.getName(), subTaskId
      );
    }
  }

  private File getIntervalDistributionDir(Interval interval)
  {

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Free disk space on the worker or increase the task's temp/storage allocation, then retry the task.
2. Check the wrapped cause (the IOException) in the stack trace for the precise filesystem error.
3. Ensure nothing external (cleanup jobs, tmpwatch) deletes Druid task temp directories during task execution.
4. Verify write permissions on the configured druid.indexer.task.baseTaskDir.

catch (IllegalStateException e) { if (e.getMessage().contains("Exception while writing distribution file")) { checkDiskSpace(); retryTask(); } else { throw e; } }

When it happens

Trigger: IOException while writing the distribution JSON for a sub-task's interval: disk full, task temp dir removed mid-run, or filesystem permission issues.

Common situations: Middle Manager / indexer nodes running out of disk space; tmp reaper or cleanup job deleting druid task temp dirs while the task runs; container ephemeral storage limits exceeded.

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

• Error while reading distribution for interval [%s], task [%s
• Input stream is null
• partitionDimensions must be specified
• DimensionDistributionPhaseRunner has been stopped. %s
• Exception while waiting to extract distributions.

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