apache/cassandra · error · ConfigurationException

%s

Error message

%s

What it means

When createInternal reflectively instantiates a replication strategy class, any exception thrown inside the strategy's constructor is wrapped in InvocationTargetException. Cassandra unwraps it and rethrows ConfigurationException with the target exception's own message (the %s placeholder). The real cause text is whatever the strategy constructor reported (e.g. a bad replication factor or unknown option).

Source

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

        return null;
    }

    private static AbstractReplicationStrategy createInternal(String keyspaceName,
                                                              Class<? extends AbstractReplicationStrategy> strategyClass,
                                                              Map<String, String> strategyOptions)
        throws ConfigurationException
    {
        AbstractReplicationStrategy strategy;
        Class<?>[] parameterTypes = new Class[] {String.class, Map.class};
        try
        {
            Constructor<? extends AbstractReplicationStrategy> constructor = strategyClass.getConstructor(parameterTypes);
            strategy = constructor.newInstance(keyspaceName, strategyOptions);
        }
        catch (InvocationTargetException e)
        {
            Throwable targetException = e.getTargetException();
            throw new ConfigurationException(targetException.getMessage(), targetException);
        }
        catch (Exception e)
        {
            throw new ConfigurationException("Error constructing replication strategy class", e);
        }
        return strategy;
    }

    public static AbstractReplicationStrategy createReplicationStrategy(String keyspaceName,
                                                                        ReplicationParams replicationParams)
    {
        return createReplicationStrategy(keyspaceName, replicationParams.klass, replicationParams.options);
    }
    public static AbstractReplicationStrategy createReplicationStrategy(String keyspaceName,
                                                                        Class<? extends AbstractReplicationStrategy> strategyClass,
                                                                        Map<String, String> strategyOptions)
    {
        AbstractReplicationStrategy strategy = createInternal(keyspaceName, strategyClass, strategyOptions);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Read the inner message: it names the constructor argument that failed validation
2. Correct the replication options in the CREATE/ALTER KEYSPACE statement
3. Use valid syntax: {'class': 'NetworkTopologyStrategy', 'dc1': '3'} — RF values must be positive integers or 'N/short' transient forms
4. Validate the strategy options first via AbstractReplicationStrategy.validateReplicationStrategy

Example fix

// before
CREATE KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':'abc'};
// after
CREATE KEYSPACE ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':'3'};

// Validate strategy options before issuing CREATE/ALTER KEYSPACE
Map<String,String> opts = replication;
String rf = opts.get("replication_factor");
if (rf != null && !rf.matches("\\d+(/\\d+)?")) throw new IllegalArgumentException("Bad RF: " + rf);

try {
    session.execute("CREATE KEYSPACE ks WITH replication = ?", replicationMap);
} catch (ConfigurationException e) {
    // message contains the constructor's complaint about the offending option
    logger.error("Invalid replication options: {}", e.getMessage());
}

When it happens

Trigger: CREATE KEYSPACE / ALTER KEYSPACE with a replication option that the strategy constructor rejects — e.g. NetworkTopologyStrategy with an invalid RF like 'dc1: abc' or SimpleStrategy with non-numeric replication_factor.

Common situations: Typo'd replication_factor ('3L', 'three'), negative or zero RF, per-DC RF strings with bad format, invalid option names in replication map.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• default_keyspace_rf cannot be less than 1
• Unrecognized strategy option {%s} passed to %s for keyspace
• Invalid data rate: value must be non-negative
• Invalid data storage: %s Accepted units:%s
• default_keyspace_rf (%d) cannot be less than minimum_replica

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