What causes "Column[%d] is not a key column" in apache/druid?

Join only on columns that were declared as key columns when building the RowBasedIndexedTable

apache/druid · error · IllegalArgumentException

Column[ ] is not a key column

Error message

Column[%d] is not a key column

What it means

Thrown by RowBasedIndexedTable.getKeyColumnIndex when the requested column index does not correspond to a key column of the row-based indexed table (the indexes list entry is null). The join machinery only supports lookups and joins on columns designated as keys; querying a non-key column index is a programming/configuration error.

Solutions

Join only on columns that were declared as key columns when building the RowBasedIndexedTable
Verify the column index passed to columnIndex matches the intended key column position in the table's key list
Inspect the table's keyColumns/signature to confirm which positions are keys
If the column must be joinable, rebuild the table including it in the key columns

Example fix

// before
Index idx = RowBasedIndexedTable.getKeyColumnIndex(5, indexes); // 5 is a value column
// after
int keyPos = table.keyColumns().indexOf("colName");
Index idx = keyPos >= 0 ? RowBasedIndexedTable.getKeyColumnIndex(keyPos, indexes) : null;

Defensive patterns

Strategy: validation

Validate before calling

int keyPos = table.getNonTimeColumnIndex candidate; if (keyPos < 0 || keyPos >= table.keyColumns().size()) throw new IllegalArgumentException("not a key column: " + col);

Type guard

boolean isKeyColumn(RowBasedIndexedTable t, String col) { return t.keyColumns() != null && t.keyColumns().contains(col); }

Try / catch

try { idx = table.columnIndex(col); } catch (IAE e) { log.warn("Not a key column, falling back to non-joinable path"); idx = null; }

Prevention

Only join on columns declared as key columns in the indexed table
Log table key columns at build time for debugging join configs
Validate join condition columns against keyColumns before executing

When it happens

Trigger: Calling columnIndex(...) on a RowBasedIndexedTable with a column position that is beyond the key columns or points at a value (non-key) column; a join spec references a non-key column as the join key.

Common situations: Joining a broadcast RowBasedIndexedTable on a column that was not declared as a key when the table was built; off-by-one when computing the column index from a row signature; join condition rewritten after the table was built with different key columns.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/join/table/RowBasedIndexedTable.java:196

  @Override
  public Optional<Closeable> acquireReference()
  {
    // nothing to close by default, whatever loaded this thing (probably) lives on heap
    return Optional.of(() -> {});
  }

  @Override
  public void close()
  {
    // nothing to close
  }

  static Index getKeyColumnIndex(int column, List<Index> indexes)
  {
    final Index index = indexes.get(column);

    if (index == null) {
      throw new IAE("Column[%d] is not a key column", column);
    }

    return index;
  }
}

View on GitHub (pinned to 9b90983fd2)