apache/druid · error · IllegalArgumentException

Parameter fieldName must be specified

Error message

Parameter fieldName must be specified

What it means

The KLL aggregator factory requires a fieldName — the input column whose values feed the sketch. Without it the aggregator cannot know what to aggregate, so the constructor throws IAE when fieldName is null.

Source

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

  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) {
        return new KllSketchNoOpAggregator<>(getEmptySketch());
      }
      return getBuildAggregator(selector);
    }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Add the "fieldName" property pointing at the input column containing floats or serialized sketches.
2. Verify the input column exists in the datasource/row schema with the expected name.
3. For merge aggregators, ensure fieldName references the column holding previously-built sketch objects.

Example fix

// before
{"type": "KLL_FLOATS_SKETCH_BUILD", "name": "kll_sketch"}

// after
{"type": "KLL_FLOATS_SKETCH_BUILD", "name": "kll_sketch", "fieldName": "value_col"}

if (aggSpec.getFieldName() == null) {
  throw new IllegalArgumentException("Aggregator spec requires 'fieldName'");
}

try {
  AggregatorFactory factory = buildKllFactory(name, fieldName, k, maxStreamLength);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("fieldName")) {
    // resolve a default input column or fail fast with a clear message
    throw new IllegalArgumentException("KLL aggregator needs a valid input column");
  } else throw e;
}

When it happens

Trigger: Creating a KLL build/merge aggregator factory (or JSON spec) without the 'fieldName' property, e.g. {"type": "KLL_FLOATS_SKETCH_BUILD", "name": "kll"} with no fieldName.

Common situations: Copy-pasting an aggregation spec and deleting the fieldName, or building aggregators dynamically over columns where the column name resolved to null (e.g. missing dimension in the input schema).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Must have a valid, non-null aggregator name
• 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/dffbabe64af5c3b0. Report an issue: GitHub.