What causes "Empty columns" in apache/druid?

Set an explicit 'columns' list in the inputFormat so the header is not relied upon

apache/druid · error · IllegalStateException

Empty columns

Error message

Empty columns

What it means

Thrown by DelimitedValueReader.setSignature when the header line of a delimited (CSV/TSV) input yields zero columns, so no InputRowSignature can be built. The library cannot parse records without a column list, so it fails fast during input-format initialization.

Source

Thrown at processing/src/main/java/org/apache/druid/data/input/impl/DelimitedValueReader.java:185

  public void processHeaderLine(byte[] line) throws IOException
  {
    if (!findColumnsFromHeader) {
      throw new ISE("Don't call this if findColumnsFromHeader = false");
    }
    setSignature(parser.parseLine(line));
  }

  /**
   * Set {@link #inputRowDimensions} and {@link #inputRowSignature} based on a set of header columns. Must be called
   * prior to {@link #parseInputRows(byte[])}.
   *
   * @param columns header columns
   */
  private void setSignature(final List<String> columns)
  {
    inputRowSignature = findOrCreateInputRowSignature(columns);
    if (inputRowSignature.size() == 0) {
      throw new ISE("Empty columns");
    }

    inputRowDimensions = MapInputRowParser.findDimensions(
        getInputRowSchema().getTimestampSpec(),
        getInputRowSchema().getDimensionsSpec(),
        ImmutableSet.copyOf(inputRowSignature.getColumnNames())
    );
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

Set an explicit 'columns' list in the inputFormat so the header is not relied upon
Verify the 'delimiter' and 'listDelimiter' match the actual file format
Check that the input file is non-empty and actually contains a header line as its first row
Skip leading blank lines or re-export the file without a BOM/blank header

Example fix

// before
"inputFormat": {"type": "csv", "findColumnsFromHeader": true} // file has no header
// after
"inputFormat": {"type": "csv", "columns": ["ts", "user", "value"]}

Defensive patterns

Strategy: validation

Validate before calling

// Before ingestion, verify the header yields columns
List<String> header = readFirstLine(file, delimiter);
if (header == null || header.stream().allMatch(String::isBlank)) {
    throw new IllegalArgumentException("Input file has no usable header; set explicit columns");
}

Try / catch

try { reader.beginParsing(); } catch (IllegalStateException e) { if (e.getMessage().contains("Empty columns")) { /* fall back to explicit columns */ } }

Prevention

Always ship an explicit 'columns' list for delimited formats in production specs
Validate delimiter/listDelimiter against a sample of the real file before submitting the task
Check files for BOMs and blank first lines in your upload pipeline

When it happens

Trigger: Using DelimitedValueReader/DelimitedInputFormat with findColumnsFromHeader=true on a file whose first line is blank or whose header parses to an empty column list (e.g. wrong delimiter so the whole header is one empty token, or an empty file).

Common situations: Pointing ingestion at an empty file or a file with only a BOM/blank first line; a delimiter mismatch (e.g. file is semicolon-delimited but configured as comma) making column parsing degenerate; header row absent but findColumnsFromHeader enabled.

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

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