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

LocalStrategy is reserved for internal (system) keyspaces only. A CREATE KEYSPACE explicitly specifying class LocalStrategy is rejected to prevent users from creating user keyspaces whose data is replicated locally-only and managed by the system.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/CreateKeyspaceStatement.java:104

        Keyspaces schema = metadata.schema.getKeyspaces();
        if (schema.containsKeyspace(keyspaceName))
        {
            if (ifNotExists)
                return schema;

            throw new AlreadyExistsException(keyspaceName);
        }

        // we deduplicate ReplicationParams here to use the same objects in KeyspaceMetadata
        // as we have as keys in metadata.placements to have a fast map lookup
        // ReplicationParams are immutable, so it is a safe optimization
        KeyspaceParams keyspaceParams = attrs.asNewKeyspaceParams();
        ReplicationParams replicationParams = metadata.placements().deduplicateReplicationParams(keyspaceParams.replication);
        keyspaceParams = keyspaceParams.withSwapped(replicationParams);
        KeyspaceMetadata keyspaceMetadata = KeyspaceMetadata.create(keyspaceName, keyspaceParams);

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

        if (keyspaceMetadata.params.replication.isMeta())
            throw ire("Can not create a keyspace with MetaReplicationStrategy");

        keyspaceMetadata.params.validate(keyspaceName, state, metadata);
        keyspaceMetadata.replicationStrategy.validateExpectedOptions(metadata);

        expandedCql = keyspaceMetadata.toCqlString(false, true, ifNotExists);
        verifyExpandedCql(expandedCql);
        return schema.withAddedOrUpdated(keyspaceMetadata);
    }

    SchemaChange schemaChangeEvent(KeyspacesDiff diff)
    {
        return new SchemaChange(Change.CREATED, keyspaceName);
    }

    public void authorize(ClientState client)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use SimpleStrategy or NetworkTopologyStrategy for user keyspaces.
2. For a single-node-local feel, use SimpleStrategy with replication_factor: 1 instead.
3. If the intent was per-datacenter behavior, use NetworkTopologyStrategy with explicit RF per DC.

Example fix

// before
CREATE KEYSPACE ks WITH replication = {'class': 'LocalStrategy'};

// after
CREATE KEYSPACE ks WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 3};

String cls = extractReplicationClass(cql); if ("LocalStrategy".equals(cls)) throw new IllegalArgumentException("LocalStrategy is reserved for internal use");

try { session.execute(ddl); } catch (InvalidQueryException e) { if (e.getMessage().contains("LocalStrategy is reserved")) { /* swap to SimpleStrategy/NetworkTopologyStrategy */ } else throw e; }

When it happens

Trigger: `CREATE KEYSPACE ks WITH replication = {'class': 'LocalStrategy'};` — detected after building KeyspaceMetadata in apply().

Common situations: Copying the replication settings from a system keyspace (system, system_schema) into a user keyspace; misunderstanding LocalStrategy as a "replication_factor=1" equivalent.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Can not create a keyspace with MetaReplicationStrategy
• Missing mandatory option '%s'
• Keyspace %s doesn't exist
• Missing replication strategy class
• Cannot use keyspace inheriting fast path strategy with keysp

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