apache/druid · error · IllegalArgumentException

Group key should be a single dimension

Error message

Group key should be a single dimension

What it means

The array-based groupBy aggregate iterator (GroupByQueryEngine) supports grouping on at most one dimension for its IntGrouper fast path. ArrayAggregateIterator's constructor throws an IAE if dims.length > 1, since multi-dimension keys cannot map to the single-int grouping it implements.

Solutions

  1. Use multiple dimensions only via the standard buffer/array grouper path (remove context flags forcing the array iterator)
  2. Split the query into multiple single-dimension groupBy queries and merge results
  3. Combine dimensions into one via a virtual column/expression (concat) before grouping
  4. Upgrade Druid — newer versions route multi-dim groupings correctly; check version-specific engine selection bugs

Example fix

// before
columns: ["dim1", "dim2"] with engine forced to array iterator
// after
columns: ["dim1"] // or remove engine-forcing context key, or use concat expression as a single key
Defensive patterns

Strategy: validation

Validate before calling

if (dims.length > 1) {
  throw new IllegalArgumentException("Array iterator path supports only a single group dimension; use the standard grouper");
}

Type guard

boolean isArrayIteratorCompatible(String[] dims) { return dims == null || dims.length <= 1; }

Try / catch

try { runArrayQuery(query); } catch (IAE e) { if (e.getMessage().equals("Group key should be a single dimension")) { fallbackToStandardGrouper(query); } }

Prevention

When it happens

Trigger: Running a groupBy query in the array-capable engine path where the grouping dimensions list resolves to 2+ dimensions for ArrayAggregateIterator — e.g. a groupBy with multiple dimensions routed to the array iterator instead of the general (buffer/array) grouper path.

Common situations: Query engine/context selection forcing the array iterator (groupBy enableArray... context flags) with multi-dim queries; auto-engine heuristics picking array path for single-dim-looking queries that actually expand to multiple dims; virtual columns expanding into multiple output dims.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/GroupByQueryEngine.java:737

        GroupByQueryConfig querySpecificConfig,
        DruidProcessingConfig processingConfig,
        Cursor cursor,
        CursorGranularizer granularizer,
        ByteBuffer buffer,
        @Nullable DateTime fudgeTimestamp,
        GroupByColumnSelectorPlus[] dims,
        boolean allSingleValueDims,
        int cardinality
    )
    {
      super(query, querySpecificConfig, processingConfig, cursor, granularizer, buffer, fudgeTimestamp, dims, allSingleValueDims);
      this.cardinality = cardinality;
      if (dims.length == 1) {
        this.dim = dims[0];
      } else if (dims.length == 0) {
        this.dim = null;
      } else {
        throw new IAE("Group key should be a single dimension");
      }
    }

    @Override
    protected IntGrouper newGrouper()
    {
      return new BufferArrayGrouper(
          Suppliers.ofInstance(buffer),
          AggregatorAdapters.factorizeBuffered(cursor.getColumnSelectorFactory(), query.getAggregatorSpecs()),
          cardinality
      );
    }

    @Override
    protected void aggregateSingleValueDims(Grouper<IntKey> grouper)
    {
      aggregateSingleValueDimsWithIntGrouper((IntGrouper) grouper);
    }

View on GitHub (pinned to 9b90983fd2)