apache/druid · error · IllegalArgumentException

Cannot have null or empty column name

Error message

Cannot have null or empty column name

What it means

The KeyColumn constructor in org.apache.druid.frame.key validates that a clustering/sorting key column has a non-null, non-empty name. KeyColumn pairs a column name with a KeyOrder and is used by frame-based sorting and clustering. The library cannot sort or compare keys without a column to reference, so any null or empty name is rejected immediately with IAE.

Source

Thrown at processing/src/main/java/org/apache/druid/frame/key/KeyColumn.java:45

import java.util.Objects;

/**
 * Represents a component of a hash or sorting key.
 */
public class KeyColumn
{
  private final String columnName;
  private final KeyOrder order;

  @JsonCreator
  public KeyColumn(
      @JsonProperty("columnName") String columnName,
      @JsonProperty("order") KeyOrder order
  )
  {
    if (columnName == null || columnName.isEmpty()) {
      throw new IAE("Cannot have null or empty column name");
    }

    this.columnName = columnName;
    this.order = order;
  }

  @JsonProperty
  public String columnName()
  {
    return columnName;
  }

  @JsonProperty
  public KeyOrder order()
  {
    return order;
  }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Pass the exact, non-empty column name that exists in the input frame (case-sensitive).
2. Before constructing KeyColumn, filter out null/blank strings from the column list.
3. If names come from user input or config, validate them upfront with a clear error pointing at the offending entry.

Example fix

// before
List<KeyColumn> key = columns.stream().map(c -> new KeyColumn(c, KeyOrder.ASCENDING)).collect(Collectors.toList());
// after
List<KeyColumn> key = columns.stream()
    .filter(c -> c != null && !c.isEmpty())
    .map(c -> new KeyColumn(c, KeyOrder.ASCENDING))
    .collect(Collectors.toList());

if (columnName == null || columnName.isEmpty()) {
  throw new IllegalArgumentException("columnName must be non-null and non-empty");
}
new KeyColumn(columnName, order);

boolean isValidKeyColumn(String name) { return name != null && !name.isEmpty(); }

try {
  KeyColumn kc = new KeyColumn(name, KeyOrder.ASCENDING);
} catch (IllegalArgumentException e) {
  // handle blank column name: skip entry or surface config error
}

When it happens

Trigger: Constructing `new KeyColumn(null, KeyOrder.ASCENDING)`, `new KeyColumn("", KeyOrder.DESCENDING)`, or building a sort key from a list that contains null/empty column names (e.g. from parsed JSON `{"columnName": ""}` or a caller-supplied column list where an entry is blank).

Common situations: Programmatic assembly of ClusterBy sort keys where column names come from user config, SQL query output, or deserialized JSON; typos that yield empty strings; iterating a schema and appending blank entries; Jackson deserialization of a KeyColumn with a missing/empty columnName property.

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

• Key is not sortable
• Invalid stageNumber [%s]
• Only positive integers or zero can be added
• Must have at least one input channel
• Partitions must all abut each other

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