apache/cassandra · error · InvalidRequestException

Missing mandatory option '%s'

Error message

Missing mandatory option '%s'

What it means

CREATE KEYSPACE requires a replication option. If the WITH attributes omit REPLICATION (e.g. `WITH DURABLE_WRITES = true` only), the statement fails because Cassandra must know how to replicate the keyspace.

Source

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

    {
        if (expandedCql != null)
            return expandedCql;
        return super.cql();
    }

    @Override
    public boolean compatibleWith(ClusterMetadata metadata)
    {
        return metadata.directory.commonSerializationVersion.isAtLeast(Version.V0);
    }

    @Override
    public Keyspaces apply(ClusterMetadata metadata)
    {
        attrs.validate();

        if (!attrs.hasOption(Option.REPLICATION))
            throw ire("Missing mandatory option '%s'", Option.REPLICATION);

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

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add a REPLICATION map: CREATE KEYSPACE ks WITH replication = {'class': 'NetworkTopologyStrategy', 'dc1': 3};
2. Use SimpleStrategy only for dev: WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}.

Example fix

// before
CREATE KEYSPACE ks WITH DURABLE_WRITES = true;

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

if (!cql.matches("(?s).*replication\\s*=\\s*\\{.*")) throw new IllegalArgumentException("CREATE KEYSPACE requires a replication option");

try { session.execute(ddl); } catch (InvalidQueryException e) { if (e.getMessage().contains("Missing mandatory option")) { /* add WITH replication = {...} */ } else throw e; }

When it happens

Trigger: `CREATE KEYSPACE ks WITH DURABLE_WRITES = true;` — attrs.hasOption(Option.REPLICATION) is false in apply().

Common situations: Hand-written DDL forgetting the replication map; tooling that emits only non-replication options; copy-paste of a snippet without its WITH clause.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Unable to use given strategy class: LocalStrategy is reserve
• Can not create a keyspace with MetaReplicationStrategy
• 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/b1b2a4909580b1e3. Report an issue: GitHub.