apache/cassandra · error · IllegalStateException

Ownership values for keyspaces with LocalStrategy are meanin

Error message

Ownership values for keyspaces with LocalStrategy are meaningless

What it means

When computing token ownership (describeOwnership / effective-ownership path), requesting ownership for a keyspace that uses LocalStrategy (system keyspaces like 'system', 'system_auth' internals) is rejected: LocalStrategy replicates to the local node only, so ownership percentages are meaningless. Thrown as IllegalStateException.

Source

Thrown at src/java/org/apache/cassandra/service/StorageService.java:4257

    /**
     * Calculates ownership. If there are multiple DC's and the replication strategy is DC aware then ownership will be
     * calculated per dc, i.e. each DC will have total ring ownership divided amongst its nodes. Without replication
     * total ownership will be a multiple of the number of DC's and this value will then go up within each DC depending
     * on the number of replicas within itself. For DC unaware replication strategies, ownership without replication
     * will be 100%.
     *
     * @throws IllegalStateException when node is not configured properly.
     */
    private LinkedHashMap<InetAddressAndPort, Float> getEffectiveOwnership(String keyspace)
    {
        ClusterMetadata metadata = ClusterMetadata.current();
        ReplicationParams replicationParams = null;
        AbstractReplicationStrategy strategy;
        if (keyspace != null)
        {
            if (isLocalSystemKeyspace(keyspace))
                throw new IllegalStateException("Ownership values for keyspaces with LocalStrategy are meaningless");

            KeyspaceMetadata keyspaceInstance = metadata.schema.getKeyspaces().getNullable(keyspace);
            if (keyspaceInstance == null)
                throw new IllegalArgumentException("The keyspace " + keyspace + ", does not exist");

            if (keyspaceInstance.replicationStrategy instanceof LocalStrategy)
                throw new IllegalStateException("Ownership values for keyspaces with LocalStrategy are meaningless");

            strategy = keyspaceInstance.replicationStrategy;
            replicationParams = keyspaceInstance.params.replication;
        }
        else
        {
            Set<String> userKeyspaces = metadata.schema.getKeyspaces()
                                                       .without(SchemaConstants.REPLICATED_SYSTEM_KEYSPACE_NAMES)
                                                       .names();

            if (userKeyspaces.size() > 0)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Exclude local/system keyspaces (those with LocalStrategy) from ownership queries
Run ownership against user keyspaces only, e.g. `nodetool describeownership my_ks` ( Cassandra 4+)
Filter keyspaces before calling effectiveOwnership() in tooling
If you just need replica data, use `nodetool describecluster`/token metadata APIs instead of ownership

Example fix

// before
nodetool describeownership system
// after
nodetool describeownership my_keyspace

Defensive patterns

Strategy: validation

Validate before calling

KeyspaceMetadata ksm = Schema.instance.getKeyspaces().getNullable(ks).orElse(null);
if (ksm != null && ksm.params.replication instanceof LocalReplicationStrategy)
    throw new IllegalArgumentException("skip LocalStrategy keyspace: " + ks);

Try / catch

try { ss.effectiveOwnership(ks); } catch (IllegalStateException e) { if (e.getMessage().contains("LocalStrategy")) { return null; } throw e; }

Prevention

Exclude system keyspaces from ownership tooling
Check replication strategy class before computing ownership
Use explicit user keyspace names in nodetool commands

When it happens

Trigger: Calling `nodetool <ks> describeownership` / StorageService.effectiveOwnership(keyspace) or describeLocalOwnership passing a local/system keyspace name (e.g. 'system', 'system_schema').

Common situations: Operators scripting ownership reports over all keyspaces from system tables; tooling iterating Schema keyspaces including local ones.

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

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