apache/druid · error · IllegalArgumentException

Cannot have a null/empty columns

Error message

Cannot have a null/empty columns[%s], name[%s]

What it means

FallbackVirtualColumn delegates queries across a list of underlying columns and therefore requires at least one column. Constructing it with a null or empty column list throws IAE at construction/deserialization time to fail fast on a useless virtual column definition.

Solutions

1. Provide at least one entry in the 'columns' array of the virtual column definition
2. Fix spec generation code so it always emits the underlying dimension specs
3. If the intent is 'no columns', remove the virtual column registration entirely instead of passing an empty list

Example fix

// before
new FallbackVirtualColumn("vc", new ArrayList<>());
// after
new FallbackVirtualColumn("vc", new ArrayList<>(List.of(DefaultDimensionSpec.of("realCol"))));

if (columns == null || columns.isEmpty()) {
  throw new IllegalArgumentException("FallbackVirtualColumn needs >=1 column");
}

boolean valid = columns != null && !columns.isEmpty();

try { new FallbackVirtualColumn(name, cols); } catch (IllegalArgumentException e) { /* fix spec before registering */ }

When it happens

Trigger: Registering a fallback virtual column via query context ('useFallback': true, virtualColumns config) with an empty list; JSON deserialization of a spec missing the 'columns' field; programmatically calling the constructor with an empty ArrayList.

Common situations: Hand-written JSON specs where 'columns' was omitted or left empty; programmatic spec generation that produced no dimension specs; copy/paste of a virtual-column definition stripped of columns.

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

• Must define exactly one of 'path' or 'pathParts'
• At least one of baseDir or files should be specified
• bucketSize must be a power of two (from 1 up to 128) but…
• Cannot make array element selector, negative array index…
• Cannot set kafka property [auto.offset.reset]. Property…

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/virtual/FallbackVirtualColumn.java:72

 * If you are using this virtual column and want to have a decorator/extraction function on your DimensionSpec,
 * it is expected that you will put it on the specs in the list rather than on the spec that references this
 * virtual column.  That is, when this virtual column resolves a dimension, it ignores the decoration from the
 * spec that it was given and instead uses the spec as defined in the list as-is to delegate to the column that
 * it chose.
 */
public class FallbackVirtualColumn implements VirtualColumn
{
  private final String name;
  private final ArrayList<DimensionSpec> columns;

  @JsonCreator
  public FallbackVirtualColumn(
      @JsonProperty("name") String name,
      @JsonProperty("columns") ArrayList<DimensionSpec> columns
  )
  {
    if (columns == null || columns.isEmpty()) {
      throw new IAE("Cannot have a null/empty columns[%s], name[%s]", columns, name);
    }

    this.name = name;
    this.columns = columns;
  }

  @JsonProperty("name")
  @Override
  public String getOutputName()
  {
    return name;
  }

  @JsonProperty("columns")
  public ArrayList<DimensionSpec> getColumns()
  {
    return columns;
  }

View on GitHub (pinned to 9b90983fd2)