apache/cassandra · error · InvalidRequestException

Can not alter a keyspace to use MetaReplicationStrategy

Error message

Can not alter a keyspace to use MetaReplicationStrategy

What it means

The keyspace's current replication strategy is MetaReplicationStrategy, and replication metadata keyspaces may not be altered (except the reserved metadata keyspace itself). apply() rejects the change to prevent users from altering replication of special internal keyspaces that would acquire Meta strategy.

Source

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

    {
        attrs.validate();

        Keyspaces schema = metadata.schema.getKeyspaces();
        KeyspaceMetadata keyspace = schema.getNullable(keyspaceName);
        if (null == keyspace)
        {
            if (!ifExists)
                throw ire("Keyspace '%s' doesn't exist", keyspaceName);
            return schema;
        }

        KeyspaceMetadata newKeyspace = keyspace.withSwapped(attrs.asAlteredKeyspaceParams(keyspace.params));

        if (attrs.getReplicationStrategyClass() != null && attrs.getReplicationStrategyClass().equals(SimpleStrategy.class.getSimpleName()))
            Guardrails.simpleStrategyEnabled.ensureEnabled(state);

        if (keyspace.params.replication.isMeta() && !keyspace.name.equals(SchemaConstants.METADATA_KEYSPACE_NAME))
            throw ire("Can not alter a keyspace to use MetaReplicationStrategy");

        if (newKeyspace.params.replication.klass.equals(LocalStrategy.class))
            throw ire("Unable to use given strategy class: LocalStrategy is reserved for internal use.");

        newKeyspace.params.validate(keyspaceName, state, metadata);
        newKeyspace.replicationStrategy.validate(metadata);

        validateNoRangeMovements();
        validateTransientReplication(keyspace, newKeyspace);

        // Because we used to not properly validate unrecognized options, we only log a warning if we find one.
        try
        {
            newKeyspace.replicationStrategy.validateExpectedOptions(metadata);
        }
        catch (ConfigurationException e)
        {
            logger.warn("Ignoring {}", e.getMessage());

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Do not alter keyspaces using MetaReplicationStrategy; they are managed internally
2. Target a user keyspace with a normal (Simple/NetworkTopology) strategy instead
3. Verify the keyspace's strategy class before altering

Example fix

// before
ALTER KEYSPACE meta_ks WITH replication = {'class':'SimpleStrategy','replication_factor':1};
// after
// skip meta-strategy keyspaces; alter only user keyspaces
ALTER KEYSPACE user_ks WITH replication = {'class':'NetworkTopologyStrategy','dc1':3};

TableMetadata unused; KeyspaceMetadata ks = cluster.getMetadata().getKeyspace(keyspace); if (ks != null && ks.getReplication() != null && ks.getReplication().containsKey("class") && ks.getReplication().get("class").endsWith("MetaReplicationStrategy")) throw new IllegalStateException("meta-strategy keyspace cannot be altered");

try { session.execute(alterCql); } catch (InvalidRequestException e) { if (e.getMessage().contains("MetaReplicationStrategy")) { /* skip internal keyspace */ } else throw e; }

When it happens

Trigger: Altering a keyspace whose params.replication.isMeta() is true while its name is not SchemaConstants.METADATA_KEYSPACE_NAME; i.e., attempting to ALTER KEYSPACE on a keyspace using MetaReplicationStrategy.

Common situations: Internal/replication-metadata keyspaces targeted by automated migration scripts; confusion over which keyspaces are system-managed.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Keyspace %s doesn't exist
• Statement on keyspace %s cannot refer to a user type in keys
• Missing replication strategy class
• Cannot use keyspace inheriting fast path strategy with keysp
• Unknown keyspace: '" + keyspaceName + "'

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