apache/druid · error · IllegalArgumentException

Column[%d] is not a valid column for the frame based datasou

Error message

Column[%d] is not a valid column for the frame based datasource

What it means

FrameBasedIndexedTable.columnReader(int) checks that the requested column index exists in the table's RowSignature before creating selectors over the frame-processor-backed datasource. An out-of-range index throws this IllegalArgumentException.

Source

Thrown at processing/src/main/java/org/apache/druid/segment/join/table/FrameBasedIndexedTable.java:216

  @Override
  public int numRows()
  {
    return numRows;
  }

  @Override
  public Index columnIndex(int column)
  {
    return RowBasedIndexedTable.getKeyColumnIndex(column, keyColumnsIndexes);

  }

  @Override
  public Reader columnReader(int column)
  {

    if (!rowSignature.contains(column)) {
      throw new IAE("Column[%d] is not a valid column for the frame based datasource", column);
    }

    String columnName = rowSignature.getColumnName(column);
    final SimpleAscendingOffset offset = new SimpleAscendingOffset(numRows());
    final List<BaseObjectColumnValueSelector<?>> columnValueSelectors = new ArrayList<>();
    final Set<Closeable> closeables = new HashSet<>();

    for (QueryableIndex frameQueryableIndex : frameQueryableIndexes) {
      BaseColumnHolder columnHolder = frameQueryableIndex.getColumnHolder(columnName);
      if (columnHolder == null) {
        columnValueSelectors.add(NilColumnValueSelector.instance());
      } else {
        BaseColumn baseColumn = columnHolder.getColumn();
        columnValueSelectors.add(baseColumn.makeColumnValueSelector(offset));
        closeables.add(baseColumn);
      }
    }

View on GitHub (pinned to 9b90983fd2)

Solutions

Validate the column index against the rowSignature before requesting a reader
Re-publish/reload the frame-based datasource so its signature matches the query plan
Fix the join clause/key mapping so column indexes stay within the table's actual column count

Example fix

// before
Reader r = frameTable.columnReader(5); // only 3 columns
// after
if (column >= 0 && column < frameTable.rowSignature().size()) {
  Reader r = frameTable.columnReader(column);
}

Defensive patterns

Strategy: validation

Validate before calling

if (column < 0 || column >= rowSignature.size())
  throw new IllegalArgumentException("column " + column + " out of range for frame datasource");

Try / catch

try { r = frameTable.columnReader(col); } catch (IAE e) { log.error("frame table column index {} invalid", col); rebuildTable(); }

Prevention

Validate join column mappings against the frame's rowSignature at query planning time
Reload/rebuild the frame table after any schema change
Keep query plans and table signatures versioned together

When it happens

Trigger: Calling columnReader with an index >= rowSignature.size() (or negative) on a frame-based (dataframe-backed) indexed table, typically from join key/column mapping computed against a stale or different signature.

Common situations: Query planned against an older table signature than the loaded frame; join clause referencing more key columns than the frame datasource actually contains; schema evolution on the frame-based datasource.

Related errors

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