apache/druid · error · IllegalArgumentException

' ' cannot be used as an output name for dimensions…

Error message

'%s' cannot be used as an output name for dimensions, aggregators, or post-aggregators.

What it means

The reserved column name '__time' cannot be used as an output name for any dimension, aggregator, or post-aggregator in a GroupByQuery; the constructor checks outputNames against ColumnHolder.TIME_COLUMN_NAME and throws IAE.

Solutions

1. Rename the output (e.g. to 'timestamp' or 'time') and, if needed, extract the timestamp via an extractionFn or a time-floor expression
2. Use a granularity/extract dimension on __time only for grouping with a different output alias
3. Never alias any output to the literal '__time' string

Example fix

// before
new DefaultDimensionSpec("__time", "__time")
// after
new DefaultDimensionSpec("__time", "timestamp")

if (outputNames.contains("__time")) throw new IllegalArgumentException("'__time' is a reserved output name");

boolean usesReservedTimeColumn(GroupByQuery.Builder b, Collection<String> names) { return names.contains(ColumnHolder.TIME_COLUMN_NAME); }

try { build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("__time")) { /* rename output */ } throw e; }

When it happens

Trigger: Building/deserializing a query where any dimension outputName, aggregator name, or post-aggregator name equals '__time' (ColumnHolder.TIME_COLUMN_NAME).

Common situations: Trying to group on or alias the timestamp column as '__time'; generated queries naming outputs after the underlying segment column; users not realizing __time is reserved.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Duplicate output name
• Should only have one interval, got
• Ambiguous build, limit
• Ambiguous build, limitSpec
• buffer for list is too small, was

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/query/groupby/GroupByQuery.java:917

      if (!outputNames.add(dimension.getOutputName())) {
        throw new IAE("Duplicate output name[%s]", dimension.getOutputName());
      }
    }

    for (AggregatorFactory aggregator : aggregators) {
      if (!outputNames.add(aggregator.getName())) {
        throw new IAE("Duplicate output name[%s]", aggregator.getName());
      }
    }

    for (PostAggregator postAggregator : postAggregators) {
      if (!outputNames.add(postAggregator.getName())) {
        throw new IAE("Duplicate output name[%s]", postAggregator.getName());
      }
    }

    if (outputNames.contains(ColumnHolder.TIME_COLUMN_NAME)) {
      throw new IAE(
          "'%s' cannot be used as an output name for dimensions, aggregators, or post-aggregators.",
          ColumnHolder.TIME_COLUMN_NAME
      );
    }
  }

  public static class OrderingAndDimensions
  {
    Ordering<ResultRow> rowOrdering;
    List<DimensionSpec> dimensions;

    public OrderingAndDimensions(Ordering<ResultRow> rowOrdering, List<DimensionSpec> dimensions)
    {
      this.rowOrdering = rowOrdering;
      this.dimensions = dimensions;
    }

    public Ordering<ResultRow> getRowOrdering()

View on GitHub (pinned to 9b90983fd2)