apache/cassandra · error · ConfigurationException

Transient replication is not supported with vnodes yet

Error message

Transient replication is not supported with vnodes yet

What it means

Transient replication is only supported with single-token-per-node deployments. When a keyspace is altered to use a nonzero transient replication factor on a node configured with more than one token (vnodes), apply-time validation throws this ConfigurationException.

Source

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

    private void validateTransientReplication(KeyspaceMetadata current, KeyspaceMetadata proposed)
    {
        //If there is no read traffic there are some extra alterations you can safely make, but this is so atypical
        //that a good default is to not allow unsafe changes
        if (allow_unsafe_transient_changes)
            return;

        ReplicationFactor oldRF = current.replicationStrategy.getReplicationFactor();
        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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove the transient component (use e.g. '3' instead of '3/1') in the replication options.
2. Migrate the cluster to a single-token configuration before enabling transient replication.
3. Keep RF settings purely full replicas on vnode clusters.

Example fix

// before
"ALTER KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':'3/1'}";
// after
"ALTER KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':3}";

if (transientReplicasRequested > 0 && DatabaseDescriptor.getNumTokens() > 1) throw new IllegalArgumentException("transient replication requires single-token nodes");

try { session.execute(alterKeyspace); } catch (ConfigurationException e) { if (e.getMessage().contains("Transient replication is not supported with vnodes")) stripTransientComponent(replication); else throw e; }

When it happens

Trigger: `ALTER KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':'3/1'}` (transient replicas > 0) while DatabaseDescriptor.getNumTokens() > 1 on the coordinator node.

Common situations: Enabling transient replication on a vnode-based cluster (the default install uses num_tokens=16) without first moving to single-token assignment.

Related errors

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

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