apache/cassandra · error · UnsupportedOperationException

The index %s has not yet been upgraded to support prefix que

Error message

The index %s has not yet been upgraded to support prefix queries in CONTAINS mode. Wait for compaction or rebuild the index.

What it means

Prefix (non-CONTAINS) SASI queries in CONTAINS-mode indexes require per-sstable indexes with 'marked partial' tokens written by the newer format. TermIterator.build throws this UnsupportedOperationException when a per-SSTable index is still in CONTAINS mode without markedPartials support, i.e. the SSTable index was written by an older version.

Source

Thrown at src/java/org/apache/cassandra/index/sasi/TermIterator.java:105

        RangeIterator<Long, Token> memtableIterator = e.index.searchMemtable(e);
        if (memtableIterator != null)
        {
            tokens.add(memtableIterator);
            tokenCount.addAndGet(memtableIterator.getCount());
        }

        final Set<SSTableIndex> referencedIndexes = new CopyOnWriteArraySet<>();

        try
        {
            final CountDownLatch latch = newCountDownLatch(perSSTableIndexes.size());
            final ExecutorService searchExecutor = SEARCH_EXECUTOR.get();

            for (final SSTableIndex index : perSSTableIndexes)
            {
                if (e.getOp() == PREFIX &&
                    index.mode() == CONTAINS && !index.hasMarkedPartials())
                    throw new UnsupportedOperationException(format("The index %s has not yet been upgraded " +
                                                                          "to support prefix queries in CONTAINS mode. " +
                                                                          "Wait for compaction or rebuild the index.",
                                                                          index.getPath()));


                if (!index.reference())
                {
                    latch.decrement();
                    continue;
                }

                // add to referenced right after the reference was acquired,
                // that helps to release index if something goes bad inside of the search
                referencedIndexes.add(index);

                searchExecutor.submit((Runnable) () -> {
                    try
                    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Trigger compaction on the table (nodetool compact <keyspace> <table>) so old SSTable indexes are rewritten with marked partials.
Or rebuild the index: DROP INDEX then CREATE CUSTOM INDEX again.
Re-run the query once all SSTables have been rewritten.
Avoid PREFIX queries on that column until upgrade/compaction completes.

Example fix

// before (query fails until compaction)
SELECT * FROM users WHERE email PREFIX ?; // or CONTAINS on old index
// after: rebuild the index
DROP INDEX users_email_idx;
CREATE CUSTOM INDEX users_email_idx ON users (email) USING 'org.apache.cassandra.index.sasi.SASIIndex'
  WITH OPTIONS = {'target': 'email', 'mode': 'CONTAINS', 'analyzed': 'true'};

Defensive patterns

Strategy: validation

Validate before calling

// after upgrade, before issuing PREFIX queries on CONTAINS indexes:
// run nodetool compact <ks> <table> and confirm all SSTables are rewritten,
// or proactively rebuild: DROP INDEX ...; CREATE CUSTOM INDEX ...;

Try / catch

try {
    session.execute(prefixQuery);
} catch (UnsupportedOperationException e) {
    if (e.getMessage().contains("has not yet been upgraded to support prefix queries")) {
        scheduleIndexRebuild();
        return fallbackToContainsQuery();
    }
    throw e;
}

Prevention

After upgrading Cassandra, always compact or rebuild SASI indexes before running mixed PREFIX/CONTAINS queries.
Include SASI index rebuild in the rolling-upgrade runbook.
Avoid restoring pre-upgrade SSTable backups onto newer nodes.

When it happens

Trigger: Executing a PREFIX (or mixed PREFIX/CONTAINS) expression against a SASI index where at least one SSTable's on-disk index predates the marked-partials format: index.mode() == CONTAINS and !index.hasMarkedPartials().

Common situations: Upgrading Cassandra with existing SASI indexes and querying before compaction rewrites old SSTables; restoring old SSTable backups under a new version; running mixed-version clusters during rolling upgrade.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/a3484fb12f5b0f55. Report an issue: GitHub.