apache/cassandra · error · InvalidRequestException

Unable to use given strategy class: LocalStrategy is reserve

Error message

Unable to use given strategy class: LocalStrategy is reserved for internal use.

What it means

The ALTER KEYSPACE would set the replication strategy class to LocalStrategy, which is reserved for internal system keyspaces and cannot be assigned by users. apply() compares the new keyspace's replication klass to LocalStrategy and throws.

Source

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

        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());
        }

        return schema.withAddedOrUpdated(newKeyspace);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use SimpleStrategy or NetworkTopologyStrategy instead of LocalStrategy
2. Remove the replication-class override inherited from system keyspace templates
3. Re-run the DDL with an allowed strategy class

Example fix

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

String cls = replicationOptions.get("class"); if (cls != null && cls.endsWith("LocalStrategy")) throw new IllegalArgumentException("LocalStrategy is reserved for internal use");

try { session.execute(alterCql); } catch (InvalidRequestException e) { if (e.getMessage().contains("LocalStrategy")) { /* switch to NetworkTopologyStrategy and retry */ } else throw e; }

When it happens

Trigger: `ALTER KEYSPACE ks WITH replication = {'class':'LocalStrategy'}` (or copying params from an internal keyspace like system_auth's LocalStrategy-based cousins).

Common situations: Copying replication settings from a system keyspace verbatim; typos or misconfigured migration tooling emitting LocalStrategy.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Missing replication strategy class
• Cannot use keyspace inheriting fast path strategy with keysp
• Can not alter a keyspace to use MetaReplicationStrategy
• Missing mandatory option '%s'
• Unable to use given strategy class: LocalStrategy is reserve

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