apache/druid · error · IllegalArgumentException

Must have a valid, non-null aggregator name

Error message

Must have a valid, non-null aggregator name

What it means

KllSketchAggregatorFactory's constructor validates its arguments up front: the aggregator output name must be non-null because every aggregator needs a name to expose its results in the query result row. A null name throws IAE at construction time (query parse/spec validation), before any data is processed.

Source

Thrown at extensions-core/datasketches/src/main/java/org/apache/druid/query/aggregation/datasketches/kll/KllSketchAggregatorFactory.java:64

  // Used for sketch size estimation.
  public static final long DEFAULT_MAX_STREAM_LENGTH = 1_000_000_000;

  private final String name;
  private final String fieldName;
  private final int k;
  private final long maxStreamLength;
  private final byte cacheTypeId;

  KllSketchAggregatorFactory(
      final String name,
      final String fieldName,
      @Nullable final Integer k,
      @Nullable final Long maxStreamLength,
      final byte cacheTypeId
  )
  {
    if (name == null) {
      throw new IAE("Must have a valid, non-null aggregator name");
    }
    this.name = name;
    if (fieldName == null) {
      throw new IAE("Parameter fieldName must be specified");
    }
    this.fieldName = fieldName;
    this.k = k == null ? DEFAULT_K : k;
    this.maxStreamLength = maxStreamLength == null ? DEFAULT_MAX_STREAM_LENGTH : maxStreamLength;
    this.cacheTypeId = cacheTypeId;
  }

  @Override
  public Aggregator factorize(final ColumnSelectorFactory metricFactory)
  {
    if (metricFactory.getColumnCapabilities(fieldName) != null
        && metricFactory.getColumnCapabilities(fieldName).isNumeric()) {
      final ColumnValueSelector<ValueType> selector = metricFactory.makeColumnValueSelector(fieldName);
      if (selector instanceof NilColumnValueSelector) {

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Provide a non-null 'name' in the aggregator spec, matching the column name you want in results.
2. If using JSON ingestion/query specs, add the missing "name" field.
3. Validate aggregator factory parameters before constructing them in code.

Example fix

// before
new KllFloatsSketchBuildAggregatorFactory(null, "sketch_col", null, null)

// after
new KllFloatsSketchBuildAggregatorFactory("kll_sketch", "sketch_col", null, null)

if (aggSpec.getName() == null) {
  throw new IllegalArgumentException("Aggregator spec requires a non-null 'name'");
}

try {
  AggregatorFactory factory = buildKllFactory(name, fieldName, k, maxStreamLength);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("non-null aggregator name")) {
    // supply a default name and retry
    factory = buildKllFactory("kll_sketch", fieldName, k, maxStreamLength);
  } else throw e;
}

When it happens

Trigger: Constructing a KLL aggregator factory (KllFloatsSketchBuildAggregatorFactory, KllFloatsSketchMergeAggregatorFactory, or via JSON spec) with name = null, e.g. {"type": "KLL_FLOATS_SKETCH_BUILD", "fieldName": "x"} without a 'name' field in some programmatic paths.

Common situations: Building aggregator specs programmatically and forgetting the name key, or deserialization paths where the name field was omitted.

Related errors

• Parameter fieldName must be specified
• Not implemented
• AggregatorFactoryNotMergeableException(this, other)
• Object is not of a type that can be deserialized to a quanti
• Comparing histograms is not supported

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