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

validateReplicationFactor parses the replication_factor string into a ReplicationFactor and, if the RF includes transient replicas, checks the node's num_tokens setting. Transient replication is only supported with a single token per node (see CASSANDRA-15260); with num_tokens > 1 (vnodes) it throws this ConfigurationException.

Source

Thrown at src/java/org/apache/cassandra/locator/AbstractReplicationStrategy.java:365

                                                                                             AbstractReplicationStrategy.class);
        return strategyClass;
    }

    public boolean hasSameSettings(AbstractReplicationStrategy other)
    {
        return getClass().equals(other.getClass()) && getReplicationFactor().equals(other.getReplicationFactor());
    }

    protected void validateReplicationFactor(String s) throws ConfigurationException
    {
        try
        {
            ReplicationFactor rf = ReplicationFactor.fromString(s);
            
            if (rf.hasTransientReplicas())
            {
                if (DatabaseDescriptor.getNumTokens() > 1)
                    throw new ConfigurationException("Transient replication is not supported with vnodes yet");
            }
        }
        catch (IllegalArgumentException e)
        {
            throw new ConfigurationException(e.getMessage());
        }
    }

    public void validate(ClusterMetadata snapshot) throws ConfigurationException
    {
        validateExpectedOptions(snapshot);
        validateOptions();
        maybeWarnOnOptions();
        if (hasTransientReplicas() && !DatabaseDescriptor.isTransientReplicationEnabled())
        {
            throw new ConfigurationException("Transient replication is disabled. Enable in cassandra.yaml to use.");
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set num_tokens: 1 in cassandra.yaml (requires re-tokening the cluster) to use transient replication
Drop the transient portion of the RF (e.g. '5/1' -> '5') if staying on vnodes
Use a separate single-token cluster for transient replication experiments
Check num_tokens per datacenter (num_tokens_per_dc) if using per-DC token settings

Example fix

// before (cassandra.yaml)
num_tokens: 16
// after
num_tokens: 1

Defensive patterns

Strategy: validation

Validate before calling

// Transient RF requires single-token nodes
if (rfString.contains("/") && numTokens > 1)
    throw new IllegalArgumentException("Transient replication requires num_tokens=1");

Try / catch

try {
    session.execute("CREATE KEYSPACE ks WITH replication = {'class':'SimpleStrategy','replication_factor':'5/1'}");
} catch (ConfigurationException e) {
    logger.error("Transient RF unsupported here: {}", e.getMessage());
}

Prevention

Only attempt transient replication on single-token (num_tokens=1) clusters
Plan re-tokening before adopting transient replication
Keep RF strings without '/' when running vnodes
Record token layout (num_tokens per DC) in cluster documentation

When it happens

Trigger: Creating/altering a keyspace with RF like '5/1' (transient) on a cluster where num_tokens in cassandra.yaml is greater than 1.

Common situations: Testing transient replication on a vnode-based cluster (the default modern config uses multiple tokens); following transient replication docs without realizing the single-token requirement.

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

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