apache/cassandra · error · ConfigurationException

Cannot use transient replication on keyspaces using secondar

Error message

Cannot use transient replication on keyspaces using secondary indexes

What it means

A keyspace using secondary indexes cannot enable transient replication, because 2i write/read paths also assume full replicas. Validation fires when altering a keyspace that has any table with indexes to a nonzero transient replication factor.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/AlterKeyspaceStatement.java:210

        ReplicationFactor newRF = proposed.replicationStrategy.getReplicationFactor();

        int oldTrans = oldRF.transientReplicas();
        int oldFull = oldRF.fullReplicas;
        int newTrans = newRF.transientReplicas();
        int newFull = newRF.fullReplicas;

        if (newTrans > 0)
        {
            if (DatabaseDescriptor.getNumTokens() > 1)
                throw new ConfigurationException(String.format("Transient replication is not supported with vnodes yet"));


            if (!current.views.isEmpty())
                throw new ConfigurationException("Cannot use transient replication on keyspaces using materialized views");

            for (TableMetadata table : current.tables)
                if (!table.indexes.isEmpty())
                    throw new ConfigurationException("Cannot use transient replication on keyspaces using secondary indexes");
        }

        //This is true right now because the transition from transient -> full lacks the pending state
        //necessary for correctness. What would happen if we allowed this is that we would attempt
        //to read from a transient replica as if it were a full replica.
        if (oldFull > newFull && oldTrans > 0)
            throw new ConfigurationException("Can't add full replicas if there are any transient replicas. You must first remove all transient replicas, then change the # of full replicas, then add back the transient replicas");

        //Don't increase transient replication factor by more than one at a time if changing number of replicas
        //Just like with changing full replicas it's not safe to do this as you could read from too many replicas
        //that don't have the necessary data. W/O transient replication this alteration was allowed and it's not clear
        //if it should be.
        //This is structured so you can convert as many full replicas to transient replicas as you want.
        boolean numReplicasChanged = oldTrans + oldFull != newTrans + newFull;
        if (numReplicasChanged && (newTrans > oldTrans && newTrans != oldTrans + 1))
            throw new ConfigurationException("Can only safely increase number of transients one at a time with incremental repair run in between each time");
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Drop the secondary indexes before enabling transient replication (and consider SASI-free/query-table alternatives compatible with your setup).
2. Use only full replicas for keyspaces with secondary indexes.
3. Move indexed tables to a keyspace that uses non-transient replication.

Example fix

// before
"ALTER KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':'3/1'}"; // ks has 2i
// after
dropIndexes(ks); // then
"ALTER KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':'3/1'}";

boolean hasIndexes = ksm.tables.stream().anyMatch(t -> !t.indexes.isEmpty()); if (hasIndexes && wantsTransient) throw new IllegalArgumentException("drop secondary indexes before transient replication");

try { session.execute(alterKeyspace); } catch (ConfigurationException e) { if (e.getMessage().contains("transient replication on keyspaces using secondary indexes")) dropSecondaryIndexes(ks); else throw e; }

When it happens

Trigger: `ALTER KEYSPACE ks WITH replication = {..., 'dc1':'3/1'}` where any table in ks has secondary indexes (table.indexes not empty).

Common situations: Adding transient replication to a keyspace where users created local/global secondary indexes for ad-hoc queries.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Transient replication is not supported with vnodes yet
• Cannot use transient replication on keyspaces using material
• Can't add full replicas if there are any transient replicas.
• Can only safely increase number of transients one at a time
• Cannot alter RF while some endpoints are not in normal state

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