apache/druid · error · IllegalArgumentException

Table is too large

Error message

Table is too large

What it means

Dimension selector cardinality is computed as numRows() + 1 (the +1 for null), so a table with exactly Integer.MAX_VALUE rows would overflow int. The library throws IllegalArgumentException to prevent silent integer overflow in cardinality math.

Solutions

1. Reduce the table size below Integer.MAX_VALUE rows
2. Use a different join strategy that does not require an IndexedTable dimension selector (e.g. filter/subquery pushdown)
3. Split or partition the data so the join table is smaller

Example fix

// before
if (table.numRows() >= Integer.MAX_VALUE) { /* shrink table */ }
// after
if (table.numRows() >= Integer.MAX_VALUE) {
  throw new IllegalArgumentException("Table is too large"); // existing guard; caller must shrink the table
}

if (table.numRows() == Integer.MAX_VALUE) { throw new IllegalStateException("join table too large"); }

try { int card = selector.getValueCardinality(); } catch (IllegalArgumentException e) { /* fall back to unknown cardinality */ }

When it happens

Trigger: Calling getValueCardinality() on an IndexedTableDimensionSelector whose backing IndexedTable has numRows() == Integer.MAX_VALUE (2147483647 rows).

Common situations: Extremely large broadcast/lookup tables joined in-memory; synthetic or stress tests sized to Integer.MAX_VALUE rows; misconfigured ingestion that inflates row counts.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Caching is not supported. Check `isCacheable` before…
• Cannot build hash-join matcher on non-equi-join condition
• Cannot build hash-join matcher on non-key-based condition
• Cannot join lookup with condition referring to non-key…
• Cannot join lookup with non-equi condition

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/join/table/IndexedTableDimensionSelector.java:157

  @Override
  public void inspectRuntimeShape(RuntimeShapeInspector inspector)
  {
    inspector.visit("table", table);
    inspector.visit("extractionFn", extractionFn);
  }

  /**
   * Returns the value that {@link #getValueCardinality()} would return for a particular {@link IndexedTable}.
   *
   * The value will be one higher than {@link IndexedTable#numRows()}, to account for the possibility of phantom nulls.
   *
   * @throws IllegalArgumentException if the table's row count is {@link Integer#MAX_VALUE}
   */
  static int computeDimensionSelectorCardinality(final IndexedTable table)
  {
    if (table.numRows() == Integer.MAX_VALUE) {
      throw new IllegalArgumentException("Table is too large");
    }

    return table.numRows() + 1;
  }
}

View on GitHub (pinned to 9b90983fd2)