apache/druid · error · IllegalArgumentException

Time chunk [ ] provided in replaceTimeChunks is not aligned…

Error message

Time chunk [%s] provided in replaceTimeChunks is not aligned with segmentGranularity [%s]

What it means

Validation in validateReplaceTimeChunksGranularityAligned: each interval in replaceTimeChunks must start and end on boundaries of the query's segmentGranularity so the engine can map chunks onto segments cleanly. ETERNITY is exempted. An unaligned interval means the user supplied chunk boundaries that don't line up with segmentGranularity buckets.

Solutions

1. Adjust replaceTimeChunks intervals to exact multiples of segmentGranularity (e.g. with segmentGranularity=day, use day-aligned intervals).
2. Simplify to replaceTimeChunks = ETERNITY ('1970-01-01T00:00:00Z/P1000Y') to replace all data.
3. Re-check the SQL generated by the client/tool; misaligned intervals often come from manual SQL edits.

When it happens

Trigger: Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/indexing/destination/DataSourceMSQDestination.java:292 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/indexing/destination/DataSourceMSQDestination.java:292

      // Verify that if replaceTimeChunks is provided, it is nonempty.
      if (replaceTimeChunks.isEmpty()) {
        throw new IAE("replaceTimeChunks must be null or nonempty; cannot be empty");
      }

      // Verify all provided time chunks are aligned with segmentGranularity.
      for (final Interval interval : replaceTimeChunks) {
        // ETERNITY gets a free pass.
        if (!Intervals.ETERNITY.equals(interval)) {
          final boolean startIsAligned =
              segmentGranularity.bucketStart(interval.getStart()).equals(interval.getStart());

          final boolean endIsAligned =
              segmentGranularity.bucketStart(interval.getEnd()).equals(interval.getEnd())
              || segmentGranularity.increment(segmentGranularity.bucketStart(interval.getEnd()))
                                   .equals(interval.getEnd());

          if (!startIsAligned || !endIsAligned) {
            throw new IAE(
                "Time chunk [%s] provided in replaceTimeChunks is not aligned with segmentGranularity [%s]",
                interval,
                segmentGranularity
            );
          }
        }
      }
    }
  }
}

View on GitHub (pinned to 9b90983fd2)