apache/cassandra · error · IllegalArgumentException

Can not initialize cluster with empty cluster identifier

Error message

Can not initialize cluster with empty cluster identifier

What it means

Thrown by ClusterMetadata.forceInitializedState when the supplied clusterIdentifier equals EMPTY_METADATA_IDENTIFIER. A zero/empty identifier is not a valid cluster identity, so initialization is rejected.

Solutions

1. Generate a valid non-zero cluster identifier before calling forceInitializedState.
2. Check where the identifier is loaded/persisted - fix the source that yields the empty value.
3. Add a pre-call assertion that clusterIdentifier != EMPTY_METADATA_IDENTIFIER.

Example fix

// before
int clusterId = 0; // uninitialized
metadata.forceInitializedState(clusterId, ...);
// after
int clusterId = generateClusterIdentifier();
assert clusterId != ClusterMetadata.EMPTY_METADATA_IDENTIFIER;
metadata.forceInitializedState(clusterId, ...);

if (clusterIdentifier == ClusterMetadata.EMPTY_METADATA_IDENTIFIER) throw new IllegalArgumentException("Refusing to initialize with empty cluster identifier");

try { metadata.forceInitializedState(id, addr, ver, loc); } catch (IllegalArgumentException e) { logger.error("Bad cluster identifier: {}", e.getMessage()); }

When it happens

Trigger: Calling forceInitializedState with clusterIdentifier == EMPTY_METADATA_IDENTIFIER (typically 0), e.g. an uninitialized variable or a default-constructed id passed through.

Common situations: Bootstrap tooling reading a missing/garbage cluster id from persistent storage, a serialization bug producing 0, or calling initialization before generating a random cluster identifier.

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

• Can only initialize cluster identifier once, but it was…
• Addresses differ: !=
• appendAll() can only be called on non-frozen collections
• Bad CMS state:
• Bad NodeState

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

Appendix: source

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

     * Produce a ClusterMetadata suitable for use as the base state in the INITIALIZE_CMS transformation. This should
     * only be used on the first CMS node when bootstrapping the CMS after upgrade or in a brand new cluster.
     * @param clusterIdentifier Unique identifier for split brain detection & protection
     * @param addresses The NodeAddresses of the first CMS node.
     * @param version Version info for the first CMS node.
     * @param location The rack & DC of the first CMS node.
     * @return ClusterMetadata instance in the correct state to constitute the base state of the INITIALIZE_CMS
     *         transformation
     */
    public ClusterMetadata forceInitializedState(int clusterIdentifier,
                                                 NodeAddresses addresses,
                                                 NodeVersion version,
                                                 Location location)
    {
        if (this.metadataIdentifier != EMPTY_METADATA_IDENTIFIER)
            throw new IllegalStateException(String.format("Can only initialize cluster identifier once, but it was already set to %d", this.metadataIdentifier));

        if (clusterIdentifier == EMPTY_METADATA_IDENTIFIER)
            throw new IllegalArgumentException("Can not initialize cluster with empty cluster identifier");

        if (this.epoch.isAfter(Epoch.FIRST))
            throw new IllegalStateException(String.format("Can only initialize cluster identifier during epoch %d, but current epoch is %d", Epoch.FIRST.getEpoch(), epoch.getEpoch()));

        // Maybe register the first CMS node. If upgrading from gossip, this should be a no-op
        Directory withRegistered = directory.with(addresses, location, version);
        NodeId firstNode = withRegistered.peerId(addresses.broadcastAddress);
        if (firstNode == null)
            throw new IllegalStateException("Failed to find first CMS node in directory");

        CMSMembership initialCMS = cmsMembership.startJoining(firstNode).finishJoining(firstNode);
        return new ClusterMetadata(clusterIdentifier,
                                   epoch,
                                   partitioner,
                                   schema,
                                   withRegistered,
                                   tokenMap,
                                   placements,

View on GitHub (pinned to 88fd0f6a0e)