apache/druid · error · java.lang.IllegalStateException

Multi-value row not supported

Error message

Multi-value row not supported

What it means

VariantColumn does not support multi-value (list-of-lists) rows: getMultiValueRow is an intentionally unimplemented accessor that always throws IllegalStateException. Nested variant columns expose arrays through their own mechanisms, not through the multi-value dimension row API.

Solutions

  1. Use the nested column's array accessors or SQL ARRAY functions instead of multi-value row access
  2. Rewrite the query to use UNNEST or nested column functions rather than MV dimension selectors
  3. Avoid treating variant columns as multi-value dimensions in custom code
  4. Check Druid docs for supported nested-column query paths

Example fix

// before
IndexedInts row = column.getMultiValueRow(rowNum);
// after
Object val = column.get(rowNum); // single-value or Object[] for arrays
Defensive patterns

Strategy: type-guard

Validate before calling

// check column type before MV access
if (column instanceof VariantColumn) { /* use getRowValue/objects API, not getMultiValueRow */ }

Type guard

static boolean supportsMultiValueRows(Column column) { return !(column instanceof VariantColumn); }

Try / catch

try { return column.getMultiValueRow(row); } catch (IllegalStateException e) { if (e.getMessage().equals("Multi-value row not supported")) { return SingleIndexedInt.of(...); } throw e; }

Prevention

When it happens

Trigger: Any query or engine path that calls getMultiValueRow on a variant column, e.g. a legacy multi-value dimension selector path or ingestion code treating the variant column as a multi-value string dimension.

Common situations: Queries with old-style multi-value dimension handling against nested columns; code that assumes all dictionary-encoded columns support getMultiValueRow; SQL functions expecting MV semantics applied through the raw column API.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/nested/VariantColumn.java:284

    return encodedValueColumn.size();
  }

  @Override
  public boolean hasMultipleValues()
  {
    return false;
  }

  @Override
  public int getSingleValueRow(int rowNum)
  {
    return encodedValueColumn.get(rowNum);
  }

  @Override
  public IndexedInts getMultiValueRow(int rowNum)
  {
    throw new IllegalStateException("Multi-value row not supported");
  }

  @Nullable
  @Override
  public String lookupName(int id)
  {
    if (id < stringDictionary.size()) {
      return StringUtils.fromUtf8Nullable(stringDictionary.get(id));
    } else if (id < stringDictionary.size() + longDictionary.size()) {
      return String.valueOf(longDictionary.get(id - adjustLongId));
    } else if (id < stringDictionary.size() + longDictionary.size() + doubleDictionary.size()) {
      return String.valueOf(doubleDictionary.get(id - adjustDoubleId));
    }
    return null;
  }

  @Override
  public int lookupId(String val)

View on GitHub (pinned to 9b90983fd2)