apache/cassandra · error · InvalidRequestException

A storage-attached index cannot be created over multiple col

Error message

A storage-attached index cannot be created over multiple columns:

What it means

SAI supports indexing exactly one column per index; validateOptions throws this InvalidRequestException when the target string splits on ',' into more than one column. Multi-column indexing must be expressed as multiple separate SAI indexes.

Source

Thrown at src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java:255

        {
            return unknown;
        }

        if (ILLEGAL_PARTITIONERS.contains(metadata.partitioner.getClass()))
        {
            throw new InvalidRequestException("Storage-attached index does not support the following IPartitioner implementations: " + ILLEGAL_PARTITIONERS);
        }

        String targetColumn = options.get(IndexTarget.TARGET_OPTION_NAME);

        if (targetColumn == null)
        {
            throw new InvalidRequestException("Missing target column");
        }

        if (targetColumn.split(",").length > 1)
        {
            throw new InvalidRequestException("A storage-attached index cannot be created over multiple columns: " + targetColumn);
        }

        Pair<ColumnMetadata, IndexTarget.Type> target = TargetParser.parse(metadata, targetColumn);

        if (target == null)
        {
            throw new InvalidRequestException("Failed to retrieve target column for: " + targetColumn);
        }

        // In order to support different index targets on non-frozen map, ie. KEYS, VALUE, ENTRIES, we need to put index
        // name as part of index file name instead of column name. We only need to check that the target is different
        // between indexes. This will only allow indexes in the same column with a different IndexTarget.Type.
        //
        // Note that: "metadata.indexes" already includes current index
        if (metadata.indexes.stream().filter(index -> index.getIndexClassName().equals(StorageAttachedIndex.class.getName()))
                            .map(index -> TargetParser.parse(metadata, index.options.get(IndexTarget.TARGET_OPTION_NAME)))
                            .filter(Objects::nonNull).filter(t -> t.equals(target)).count() > 1)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Create one SAI index per column
  2. Drop the multi-column target and split the statement
  3. If a composite is truly needed, query with multiple single-column SAI index predicates

Example fix

// before
CREATE CUSTOM INDEX idx ON ks.tbl (first_name, last_name) USING 'StorageAttachedIndex';
// after
CREATE CUSTOM INDEX idx_fn ON ks.tbl (first_name) USING 'StorageAttachedIndex';
CREATE CUSTOM INDEX idx_ln ON ks.tbl (last_name) USING 'StorageAttachedIndex';
Defensive patterns

Strategy: validation

Validate before calling

if (targetColumn.split(",").length > 1) throw new IllegalArgumentException("SAI supports one column per index: " + targetColumn);

Try / catch

try { session.execute(ddl); } catch (InvalidRequestException e) { if (e.getMessage().contains("multiple columns")) { /* split into per-column indexes */ } else throw e; }

Prevention

When it happens

Trigger: CREATE CUSTOM INDEX ON ks.tbl (col1, col2) USING 'StorageAttachedIndex' — the driver/grammar collapses both columns into one target string; or programmatic target like "a,b".

Common situations: Porting a multi-column legacy index definition to SAI; expecting SAI to support composite/multi-column indexes like some other engines.

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/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/30a4d6398d12d04d. Report an issue: GitHub.