{"record":{"id":"11432c846f6a4e4d","repo":"apache/cassandra","slug":"can-not-initialize-cluster-with-empty-cluster-iden","errorCode":null,"errorMessage":"Can not initialize cluster with empty cluster identifier","messagePattern":"Can not initialize cluster with empty cluster identifier","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/tcm/ClusterMetadata.java","lineNumber":486,"sourceCode":"     * Produce a ClusterMetadata suitable for use as the base state in the INITIALIZE_CMS transformation. This should\n     * only be used on the first CMS node when bootstrapping the CMS after upgrade or in a brand new cluster.\n     * @param clusterIdentifier Unique identifier for split brain detection & protection\n     * @param addresses The NodeAddresses of the first CMS node.\n     * @param version Version info for the first CMS node.\n     * @param location The rack & DC of the first CMS node.\n     * @return ClusterMetadata instance in the correct state to constitute the base state of the INITIALIZE_CMS\n     *         transformation\n     */\n    public ClusterMetadata forceInitializedState(int clusterIdentifier,\n                                                 NodeAddresses addresses,\n                                                 NodeVersion version,\n                                                 Location location)\n    {\n        if (this.metadataIdentifier != EMPTY_METADATA_IDENTIFIER)\n            throw new IllegalStateException(String.format(\"Can only initialize cluster identifier once, but it was already set to %d\", this.metadataIdentifier));\n\n        if (clusterIdentifier == EMPTY_METADATA_IDENTIFIER)\n            throw new IllegalArgumentException(\"Can not initialize cluster with empty cluster identifier\");\n\n        if (this.epoch.isAfter(Epoch.FIRST))\n            throw new IllegalStateException(String.format(\"Can only initialize cluster identifier during epoch %d, but current epoch is %d\", Epoch.FIRST.getEpoch(), epoch.getEpoch()));\n\n        // Maybe register the first CMS node. If upgrading from gossip, this should be a no-op\n        Directory withRegistered = directory.with(addresses, location, version);\n        NodeId firstNode = withRegistered.peerId(addresses.broadcastAddress);\n        if (firstNode == null)\n            throw new IllegalStateException(\"Failed to find first CMS node in directory\");\n\n        CMSMembership initialCMS = cmsMembership.startJoining(firstNode).finishJoining(firstNode);\n        return new ClusterMetadata(clusterIdentifier,\n                                   epoch,\n                                   partitioner,\n                                   schema,\n                                   withRegistered,\n                                   tokenMap,\n                                   placements,","sourceCodeStart":468,"sourceCodeEnd":504,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/tcm/ClusterMetadata.java#L468-L504","documentation":"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.","triggerScenarios":"Calling forceInitializedState with clusterIdentifier == EMPTY_METADATA_IDENTIFIER (typically 0), e.g. an uninitialized variable or a default-constructed id passed through.","commonSituations":"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.","solutions":["Generate a valid non-zero cluster identifier before calling forceInitializedState.","Check where the identifier is loaded/persisted - fix the source that yields the empty value.","Add a pre-call assertion that clusterIdentifier != EMPTY_METADATA_IDENTIFIER."],"exampleFix":"// before\nint clusterId = 0; // uninitialized\nmetadata.forceInitializedState(clusterId, ...);\n// after\nint clusterId = generateClusterIdentifier();\nassert clusterId != ClusterMetadata.EMPTY_METADATA_IDENTIFIER;\nmetadata.forceInitializedState(clusterId, ...);","handlingStrategy":"validation","validationCode":"if (clusterIdentifier == ClusterMetadata.EMPTY_METADATA_IDENTIFIER) throw new IllegalArgumentException(\"Refusing to initialize with empty cluster identifier\");","typeGuard":null,"tryCatchPattern":"try { metadata.forceInitializedState(id, addr, ver, loc); } catch (IllegalArgumentException e) { logger.error(\"Bad cluster identifier: {}\", e.getMessage()); }","preventionTips":["Always generate a non-zero random cluster identifier","Validate identifiers loaded from persistent storage","Fail fast on default/zero ids before initialization"],"tags":["tcm","cluster-bootstrap","invalid-argument"],"backgroundTag":"invalid-argument-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}