apache/cassandra · error · ConfigurationException

Error constructing replication strategy class

Error message

Error constructing replication strategy class

What it means

If reflective construction of the replication strategy fails with any exception other than InvocationTargetException (e.g. ClassNotFoundException cannot happen here, but NoSuchMethodException, InstantiationException, IllegalAccessException, or IllegalArgumentException from getConstructor/newInstance), createInternal throws ConfigurationException("Error constructing replication strategy class", e). It indicates the strategy class could not be instantiated at all, rather than rejecting its options.

Source

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

                                                              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);
        strategy.validateOptions();
        return strategy;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure the strategy class is public, concrete, and has a public constructor (String keyspaceName, Map<String,String> options)
2. Check the cause chain (getCause) of the ConfigurationException for the reflective failure detail
3. Verify the plugin jar is on the classpath of every node
4. Use a built-in strategy (SimpleStrategy/NetworkTopologyStrategy) if a custom one is not required

Example fix

// before
class MyStrategy extends AbstractReplicationStrategy { public MyStrategy(String ks) {...} }
// after
class MyStrategy extends AbstractReplicationStrategy {
    public MyStrategy(String ks, Map<String,String> opts) { super(ks, opts, null); ... }
}

// Verify the strategy class is instantiable before configuring it
Class<?> c = FBUtilities.classForNameWithoutInitialization(name, "replication strategy");
if (!Modifier.isAbstract(c.getModifiers()) || c.getConstructors().length == 0)
    throw new IllegalArgumentException(name + " must be concrete with a public (String, Map) constructor");

try {
    AbstractReplicationStrategy s = AbstractReplicationStrategy.createReplicationStrategy(ks, params);
} catch (ConfigurationException e) {
    if (e.getCause() != null) logger.error("Strategy construction failed: {}", e.getCause());
}

When it happens

Trigger: A custom AbstractReplicationStrategy subclass lacking the (String, Map<String,String>) constructor, being abstract, or having a non-public constructor; passing a class name that resolves but cannot be instantiated via getClass/createReplicationStrategy.

Common situations: Custom strategy plugin jar not fully deployed or class has wrong constructor signature; strategy class modified upstream losing the required constructor; typo producing a class that exists but is abstract.

Related errors

• Failed to instantiate %s
• default_keyspace_rf (%d) cannot be less than minimum_replica
• default_keyspace_rf cannot be less than 1
• default_keyspace_rf to be set (%d) cannot be less than minim
• default_keyspace_rf to be set (%d) cannot be greater than ma

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