apache/druid · error · IllegalArgumentException

Can not supply empty segments as input, please use either nu

Error message

Can not supply empty segments as input, please use either null or non-empty segments.

What it means

TableInputSpec accepts either null segments (read via intervals/datasource) or an explicit non-empty list of segment descriptors. An explicitly empty list is ambiguous - it would mean reading zero data - so the constructor rejects it with an IAE.

Source

Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/input/table/TableInputSpec.java:70

   * @param dataSource   datasource to read
   * @param intervals    intervals to filter, or null if no time filtering is desired. Interval filtering is strict,
   *                     meaning that when this spec is sliced and read, the returned {@link LoadableSegment}
   *                     from {@link PhysicalInputSlice#getLoadableSegments()} are clipped to these intervals using
   *                     {@link LoadableSegment#descriptor()}.
   * @param segments     specific segments to read, or null to read all segments in the intervals. If provided,
   *                     only these segments will be read. Must not be empty if non-null.
   */
  @JsonCreator
  public TableInputSpec(
      @JsonProperty("dataSource") String dataSource,
      @JsonProperty("intervals") @Nullable List<Interval> intervals,
      @JsonProperty("segments") @Nullable List<SegmentDescriptor> segments
  )
  {
    this.dataSource = dataSource;
    this.intervals = intervals == null ? Intervals.ONLY_ETERNITY : intervals;
    if (segments != null && segments.isEmpty()) {
      throw new IAE("Can not supply empty segments as input, please use either null or non-empty segments.");
    }
    this.segments = segments;
  }

  @JsonProperty
  public String getDataSource()
  {
    return dataSource;
  }

  public List<Interval> getIntervals()
  {
    return intervals;
  }

  @JsonProperty("intervals")
  @JsonInclude(JsonInclude.Include.NON_NULL)
  @Nullable

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Omit the segments field entirely (null) to let Druid compute segments from intervals.
2. If segments are expected, check the upstream filtering logic that produced the empty list.
3. For genuinely zero input, use a query pattern that yields an empty result rather than an empty segments list.

Example fix

// before
new TableInputSpec("ds", null, Collections.emptyList()); // IAE
// after
new TableInputSpec("ds", null, null); // or a non-empty List<SegmentDescriptor>

if (segments != null && segments.isEmpty()) {
  segments = null; // omit rather than pass empty
}
TableInputSpec spec = new TableInputSpec(dataSource, intervals, segments);

try {
  spec = objectMapper.readValue(json, TableInputSpec.class);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("empty segments")) {
    spec = new TableInputSpec(dataSource, intervals, null);
  } else {
    throw e;
  }
}

When it happens

Trigger: Deserializing or constructing TableInputSpec from JSON where "segments": [] is provided (e.g. by query generation code or a client that serialized an empty segment list).

Common situations: Programmatic query builders that append segments but match zero segments after filtering; SQL planner bugs producing empty segment lists; hand-written MSQ task JSON with an empty segments array.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Cannot have empty worker set
• Partition count must be at least 1
• Partition count must be 1 when adjustable is true, but was [
• ClusterBy key must be sortable
• Cannot shuffle with spec [%s] and nil clusterBy

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