apache/cassandra · error · ConfigurationException

Cannot use transient replication on keyspaces using material

Error message

Cannot use transient replication on keyspaces using materialized views

What it means

A keyspace using materialized views cannot enable transient replication: the view write path cannot correctly handle transient replicas, so validation rejects altering a keyspace that has views to a nonzero transient replication factor.

Source

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

        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
        //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;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Move the materialized views to a separate keyspace with normal (non-transient) replication.
2. Drop the views before enabling transient replication and keep them in a non-transient keyspace.
3. Use full replication (no '/n' component) for keyspaces with MVs.

Example fix

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

KeyspaceMetadata ksm = Schema.instance.getKeyspaceMetadata(ks); if (!ksm.views.isEmpty() && wantsTransient) throw new IllegalArgumentException("disable transient RF for keyspaces with MVs");

try { session.execute(alterKeyspace); } catch (ConfigurationException e) { if (e.getMessage().contains("transient replication on keyspaces using materialized views")) moveViewsToSeparateKeyspace(); else throw e; }

When it happens

Trigger: `ALTER KEYSPACE ks WITH replication = {..., 'dc1':'3/1'}` on a keyspace that contains one or more materialized views (current.views not empty).

Common situations: Trying to save read capacity with transient replication on a keyspace that also hosts MVs (a common setup for denormalized reads).

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 secondar
• Can't add full replicas if there are any transient replicas.
• Can only safely increase number of transients one at a time
• Load CIDR groups cache operation not supported by %s

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