apache/cassandra · error · IllegalStateException

Cluster is not running unsafe TCM mode, can't load cluster…

Error message

Cluster is not running unsafe TCM mode, can't load cluster metadata

What it means

Thrown by CMSOperations.unsafeLoadClusterMetadata when loading cluster metadata from a snapshot file is attempted while unsafe TCM mode is disabled. This operation can overwrite the cluster's metadata state, so it requires the explicit opt-in flag.

Solutions

Enable unsafe_tcm_mode: true in cassandra.yaml and restart the node, then retry the load.
Verify the flag took effect (log/startup output or JMX) before retrying.
Re-disable unsafe_tcm_mode once the metadata load succeeds.

Example fix

// before (cassandra.yaml)
# unsafe_tcm_mode: false
// after
unsafe_tcm_mode: true

Defensive patterns

Strategy: validation

Validate before calling

if (!DatabaseDescriptor.getUnsafeTCMMode()) throw new IllegalStateException("Enable unsafe_tcm_mode and restart before loading metadata snapshots");

Try / catch

try { ops.unsafeLoadClusterMetadata(file); } catch (IllegalStateException e) { logger.error("Load rejected: {}", e.getMessage()); }

Prevention

Enable unsafe_tcm_mode before metadata restore
Run the load on the intended (CMS) node
Re-disable unsafe mode after recovery completes

When it happens

Trigger: Calling unsafeLoadClusterMetadata(String file) when DatabaseDescriptor.getUnsafeTCMMode() returns false.

Common situations: Restoring metadata from a backup snapshot during disaster recovery without having enabled unsafe_tcm_mode, or enabling it on a non-CMS node / forgetting a restart.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tcm/CMSOperations.java:290

    @Override
    public String dumpClusterMetadata(long epoch, long transformToEpoch, String version) throws IOException
    {
        return cms.dumpClusterMetadata(Epoch.create(epoch), Epoch.create(transformToEpoch), Version.valueOf(version));
    }

    @Override
    public String dumpClusterMetadata() throws IOException
    {
        return dumpClusterMetadata(Epoch.EMPTY.getEpoch(),
                                   ClusterMetadata.current().epoch.getEpoch() + 1000,
                                   NodeVersion.CURRENT.serializationVersion().toString());
    }

    @Override
    public void unsafeLoadClusterMetadata(String file) throws IOException
    {
        if (!DatabaseDescriptor.getUnsafeTCMMode())
            throw new IllegalStateException("Cluster is not running unsafe TCM mode, can't load cluster metadata " + file);
        cms.loadClusterMetadata(file);
    }

    @Override
    public void setCommitsPaused(boolean paused)
    {
        if (paused)
            cms.pauseCommits();
        else
            cms.resumeCommits();
    }

    @Override
    public boolean getCommitsPaused()
    {
        return cms.commitsPaused();
    }

View on GitHub (pinned to 88fd0f6a0e)