apache/cassandra · error · IllegalArgumentException

Core cluster metadata objects should be addressed directly,

Error message

Core cluster metadata objects should be addressed directly, not using the associated MetadataKey

What it means

ClusterMetadataTransformer.with(key, value) is only for extension (non-core) metadata. Passing a key registered in MetadataKeys.CORE_METADATA (schema, partitioner, directory, etc.) is rejected because core objects must be modified via their dedicated Transformer methods.

Source

Thrown at src/java/org/apache/cassandra/tcm/ClusterMetadata.java:936

                consensusMigrationState = new ConsensusMigrationState(Epoch.EMPTY, tableMigrationStatesBuilder.build());
            }
            else
            {
                consensusMigrationState = new ConsensusMigrationState(Epoch.EMPTY, newTableMigrationStates);
            }
            return this;
        }

        public Transformer with(ConsensusMigrationState consensusMigrationState)
        {
            this.consensusMigrationState = consensusMigrationState;
            return this;
        }

        public Transformer with(ExtensionKey<?, ?> key, ExtensionValue<?> obj)
        {
            if (MetadataKeys.CORE_METADATA.containsKey(key))
                throw new IllegalArgumentException("Core cluster metadata objects should be addressed directly, " +
                                                   "not using the associated MetadataKey");

            if (!key.valueType.isInstance(obj))
                throw new IllegalArgumentException("Value of type " + obj.getClass() +
                                                   " is incompatible with type for key " + key +
                                                   " (" + key.valueType + ")");

            extensions.put(key, obj);
            modifiedKeys.add(key);
            return this;
        }

        public Transformer withIfAbsent(ExtensionKey<?, ?> key, ExtensionValue<?> obj)
        {
            if (extensions.containsKey(key))
                return this;
            return with(key, obj);
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Use the dedicated core transformer methods (e.g. schema(), partitioner(), directory()) instead of with().
Define a genuinely new ExtensionKey for custom metadata rather than reusing core keys.
Check MetadataKeys.CORE_METADATA to see which keys are reserved.

Example fix

// before
transformer.with(MetadataKeys.SCHEMA, newSchema); // IllegalArgumentException
// after
transformer.schema(newSchema);

Defensive patterns

Strategy: validation

Validate before calling

if (MetadataKeys.CORE_METADATA.containsKey(key))
    throw new IllegalArgumentException("Use dedicated core transformer methods for " + key);

Try / catch

try {
    transformer.with(key, value);
} catch (IllegalArgumentException e) {
    logger.warn("Cannot use with() for core metadata: {}", e.getMessage());
}

Prevention

Use dedicated methods (schema(), partitioner(), etc.) for core metadata
Check MetadataKeys.CORE_METADATA before using with()
Reserve with()/without() strictly for custom ExtensionKeys

When it happens

Trigger: Calling ClusterMetadata.Transformer.with(ExtensionKey, ExtensionValue) with a key that is one of the core metadata keys contained in MetadataKeys.CORE_METADATA.

Common situations: Plugin/extension code mistakenly reusing a core key as an ExtensionKey, or refactoring that switched a dedicated transformer call (e.g. schema()) to the generic with() path.

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

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