What causes "Column name is required" in apache/druid?

Set a non-empty name on the ColumnSpec before passing it to column().

apache/druid · error · IAE

Column name is required

Error message

Column name is required

What it means

Thrown by TableBuilder.column(ColumnSpec) when the supplied ColumnSpec has a null or empty name. The catalog table builder requires every column to carry a non-empty name before it can be added to a table specification.

Source

Thrown at server/src/main/java/org/apache/druid/catalog/model/table/TableBuilder.java:189

  {
    return property(ExternalTableDefn.FORMAT_PROPERTY, format);
  }

  public TableBuilder columns(List<ColumnSpec> columns)
  {
    this.columns = columns;
    return this;
  }

  public List<ColumnSpec> columns()
  {
    return columns;
  }

  public TableBuilder column(ColumnSpec column)
  {
    if (Strings.isNullOrEmpty(column.name())) {
      throw new IAE("Column name is required");
    }
    columns.add(column);
    return this;
  }

  public TableBuilder timeColumn()
  {
    return column(Columns.TIME_COLUMN, Columns.LONG);
  }

  public TableBuilder column(String name, String sqlType)
  {
    return column(name, sqlType, null);
  }

  public TableBuilder column(String name, String sqlType, Map<String, Object> properties)
  {
    Preconditions.checkNotNull(tableType);

View on GitHub (pinned to 9b90983fd2)

Solutions

Set a non-empty name on the ColumnSpec before passing it to column().
Check the source of the column name (metadata query, JSON parse) for null or empty values.
Validate the ColumnSpec (name != null && !name.isEmpty()) before adding it to the builder.

Example fix

// before
builder.column(new ColumnSpec(null, type));
// after
builder.column(new ColumnSpec("userId", type));

Defensive patterns

Strategy: validation

Validate before calling

if (columnSpec.name() == null || columnSpec.name().isEmpty()) {
  throw new IllegalArgumentException("ColumnSpec must have a non-empty name");
}

Prevention

Always set the name when constructing a ColumnSpec (require it in your factory).
Sanity-check data sources of column names for null/empty entries.
Add an assert on name before calling builder.column().

When it happens

Trigger: Calling TableBuilder.column(new ColumnSpec()) or any ColumnSpec built without setName(...)/a name argument; programmatically constructing column specs where the name field was never populated.

Common situations: Building table specs dynamically from metadata where a column name source returned null/empty; forgetting to set the name on a ColumnSpec before adding it.

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

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