apache/druid · error · IllegalStateException

Error while reading distribution for interval [%s], task [%s

Error message

Error while reading distribution for interval [%s], task [%s]

What it means

After sub-tasks report distributions, the runner reads each persisted StringDistribution JSON file back from the task temp dir. An IOException during deserialization is wrapped in an ISE identifying the interval directory and sub-task id.

Source

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

    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)
  {
    return new File(tempDistributionsDir, toIntervalString(interval));
  }

  private File getDistributionJsonFile(File intervalDir, String subTaskId)
  {
    return new File(intervalDir, subTaskId);
  }

  /**
   * Waits for distributions from pending reports (if any) to be extracted.
   */

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Retry the ingestion task; the distribution files are transient and rebuilt on rerun.
2. Inspect the wrapped IOException to see whether the file is missing vs unreadable, and check the task temp dir contents.
3. Prevent external cleanup of Druid task temp dirs (tmpwatch/systemd-tmpfiles configs).
4. Check worker disk health and filesystem errors in system logs.

catch (IllegalStateException e) { if (e.getMessage().contains("Error while reading distribution")) { retryTask(); /* files are transient and rebuilt */ } else { throw e; } }

When it happens

Trigger: The distribution JSON file is missing, truncated, or unreadable when readDistributionFromFile() executes - e.g. the file was deleted between write and read, or disk corruption occurred.

Common situations: Task temp dir partially cleaned by external jobs; node crash/restart leaving truncated files; NFS/ephemeral-storage flakiness on Middle Managers.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Exception while writing distribution file for interval [%s],
• Object cannot be deserialized to a Moments Sketch:
• Input stream is null
• partitionDimensions must be specified
• DimensionDistributionPhaseRunner has been stopped. %s

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