apache/cassandra · warning

Initializing with cluster metadata from: {}

Error message

Initializing with cluster metadata from: {}

What it means

Startup.initialize logs that the node is initializing cluster metadata from the file named by TCM_UNSAFE_BOOT_WITH_CLUSTERMETADATA when the startup mode resolves to BOOT_WITH_CLUSTERMETADATA. This is an explicitly unsafe, operator-requested bootstrap path: instead of discovering metadata from peers or gossip, the node reinitializes its ClusterMetadata from a serialized file on disk.

Source

Thrown at src/java/org/apache/cassandra/tcm/Startup.java:179

                    else
                    {
                        // nothing more to do, so just initialize messaging
                        initMessaging.run();
                    }
                }
                break;
            case VOTE:
                logger.info("Initializing for discovery");
                initializeAsNonCmsNode(wrapProcessor);
                initializeForDiscovery(initMessaging);
                break;
            case UPGRADE:
                logger.info("Initializing from gossip");
                initializeFromGossip(wrapProcessor, initMessaging);
                break;
            case BOOT_WITH_CLUSTERMETADATA:
                String fileName = CassandraRelevantProperties.TCM_UNSAFE_BOOT_WITH_CLUSTERMETADATA.getString();
                logger.warn("Initializing with cluster metadata from: {}", fileName);
                reinitializeWithClusterMetadata(fileName, wrapProcessor, initMessaging);
                break;
        }
    }

    /**
     * Make this node the _first_ CMS node.
     * <p>
     * (1) Append PreInitialize transformation to local in-memory log.
     * (1a) Once this enacted and the distributed metadata keyspace is initialized, the PreInitialize transformation
     * will be inserted into the log table. This is required since as before this point, the keyspace was not availble
     * or configured with any replication or placements.
     * (2) Commit Initialize transformation, which holds a complete snapshot of metadata as of now.
     * Other nodes in the cluster, if there are any, will receive both of these log entries and enact them locally.
     * <p>
     * This process is applicable for gossip upgrades as well as regular vote-and-startup process.
     */
    public static void initializeAsFirstCMSNode()

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Confirm the property cassandra.tcm_unsafe_boot_with_clustermetadata is intentional; remove it for normal startup.
2. Validate the metadata file matches the cluster (host IDs, tokens) before booting with it.
3. Ensure all other nodes are stopped or consistent, since unsafe boot can diverge cluster metadata.
4. Prefer normal CMS discovery or initializeFromGossip when peers are available.

Example fix

// before: cassandra-env.sh
JVM_OPTS="$JVM_OPTS -Dcassandra.tcm_unsafe_boot_with_clustermetadata=/tmp/metadata.bin"
// after: remove the flag for normal operation
# JVM_OPTS="$JVM_OPTS -Dcassandra.tcm_unsafe_boot_with_clustermetadata=/tmp/metadata.bin"

// Refuse unsafe boot unless explicitly authorized
if (CassandraRelevantProperties.TCM_UNSAFE_BOOT_WITH_CLUSTERMETADATA.isPresent()
    && !Boolean.parseBoolean(System.getenv("ALLOW_UNSAFE_TCM_BOOT"))) {
    throw new IllegalStateException("TCM_UNSAFE_BOOT_WITH_CLUSTERMETADATA set without ALLOW_UNSAFE_TCM_BOOT");
}

When it happens

Trigger: Starting Cassandra with the system property cassandra.tcm_unsafe_boot_with_clustermetadata set to a metadata file path, which forces StartupMode.BOOT_WITH_CLUSTERMETADATA and the reinitializeWithClusterMetadata(...) code path.

Common situations: Disaster recovery where the whole cluster metadata is lost and operators restore from a captured ClusterMetadata snapshot file; test/lab setups deliberately bypassing CMS bootstrap; misuse of the flag in production configs left over from a recovery drill.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Booting with ClusterMetadata from file:
• Node %s is not a CMS member in epoch %s; members=%s
• Couldn't commit the transformation. Is the node shutting dow
• Tried to commit when in gossip mode
• Illegal state:

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