{"record":{"id":"f01c8e8a986ab480","repo":"apache/druid","slug":"column-d-is-not-a-key-column","errorCode":null,"errorMessage":"Column[%d] is not a key column","messagePattern":"Column\\[(.+?)\\] is not a key column","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/segment/join/table/RowBasedIndexedTable.java","lineNumber":196,"sourceCode":"  @Override\n  public Optional<Closeable> acquireReference()\n  {\n    // nothing to close by default, whatever loaded this thing (probably) lives on heap\n    return Optional.of(() -> {});\n  }\n\n  @Override\n  public void close()\n  {\n    // nothing to close\n  }\n\n  static Index getKeyColumnIndex(int column, List<Index> indexes)\n  {\n    final Index index = indexes.get(column);\n\n    if (index == null) {\n      throw new IAE(\"Column[%d] is not a key column\", column);\n    }\n\n    return index;\n  }\n}\n","sourceCodeStart":178,"sourceCodeEnd":202,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/segment/join/table/RowBasedIndexedTable.java#L178-L202","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nIndex idx = RowBasedIndexedTable.getKeyColumnIndex(5, indexes); // 5 is a value column\n// after\nint keyPos = table.keyColumns().indexOf(\"colName\");\nIndex idx = keyPos >= 0 ? RowBasedIndexedTable.getKeyColumnIndex(keyPos, indexes) : null;","handlingStrategy":"validation","validationCode":"int keyPos = table.getNonTimeColumnIndex candidate; if (keyPos < 0 || keyPos >= table.keyColumns().size()) throw new IllegalArgumentException(\"not a key column: \" + col);","typeGuard":"boolean isKeyColumn(RowBasedIndexedTable t, String col) { return t.keyColumns() != null && t.keyColumns().contains(col); }","tryCatchPattern":"try { idx = table.columnIndex(col); } catch (IAE e) { log.warn(\"Not a key column, falling back to non-joinable path\"); idx = null; }","preventionTips":["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"],"tags":["join","index","illegal-argument"],"backgroundTag":"invalid-argument-value","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}