apache/cassandra · error · ConfigurationException

max_space_usable_for_compactions_in_percentage must be betwe

Error message

max_space_usable_for_compactions_in_percentage must be between 0 and 1

What it means

max_space_usable_for_compactions_in_percentage is a fraction (0-1) of disk space usable for compactions. DatabaseDescriptor throws this ConfigurationException when the value is negative or greater than 1, since it is a proportion, not a percent integer.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:1245

        validateMaxConcurrentAutoUpgradeTasksConf(conf.max_concurrent_automatic_sstable_upgrades);

        if (conf.default_keyspace_rf < conf.minimum_replication_factor_fail_threshold)
        {
            throw new ConfigurationException(String.format("default_keyspace_rf (%d) cannot be less than minimum_replication_factor_fail_threshold (%d)",
                                                           conf.default_keyspace_rf, conf.minimum_replication_factor_fail_threshold));
        }

        if (conf.paxos_repair_parallelism <= 0)
            conf.paxos_repair_parallelism = Math.max(1, conf.concurrent_writes / 8);

        Paxos.setPaxosVariant(conf.paxos_variant);
        if (conf.paxos_state_purging == null)
            conf.paxos_state_purging = PaxosStatePurging.legacy;

        logInitializationOutcome(logger);

        if (conf.max_space_usable_for_compactions_in_percentage < 0 || conf.max_space_usable_for_compactions_in_percentage > 1)
            throw new ConfigurationException("max_space_usable_for_compactions_in_percentage must be between 0 and 1", false);

        if (conf.dump_heap_on_uncaught_exception && DatabaseDescriptor.getHeapDumpPath() == null)
            throw new ConfigurationException(String.format("Invalid configuration. Heap dump is enabled but cannot create heap dump output path: %s.", conf.heap_dump_path != null ? conf.heap_dump_path : "null"));

        conf.sai_options.validate();

        List<ConsistencyLevel> progressBarrierCLsArr = Arrays.asList(ALL, EACH_QUORUM, LOCAL_QUORUM, QUORUM, ONE, NODE_LOCAL);
        Set<ConsistencyLevel> progressBarrierCls = new HashSet<>(progressBarrierCLsArr);
        if (!progressBarrierCls.contains(conf.progress_barrier_min_consistency_level))
        {
            throw new ConfigurationException(String.format("Invalid value for progress_barrier_min_consistency_level %s. Allowed values: %s",
                                                           conf.progress_barrier_min_consistency_level, progressBarrierCLsArr));
        }

        if (!progressBarrierCls.contains(conf.progress_barrier_default_consistency_level))
        {
            throw new ConfigurationException(String.format("Invalid value for.progress_barrier_default_consistency_level %s. Allowed values: %s",
                                                           conf.progress_barrier_default_consistency_level, progressBarrierCLsArr));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set the value as a fraction, e.g. 0.5 for 50%
2. Clamp/remove any out-of-range value in cassandra.yaml before startup

Example fix

// before (cassandra.yaml)
max_space_usable_for_compactions_in_percentage: 50
// after
max_space_usable_for_compactions_in_percentage: 0.5

double p = conf.max_space_usable_for_compactions_in_percentage; if (p < 0 || p > 1) throw new IllegalArgumentException("max_space_usable_for_compactions_in_percentage must be a fraction in [0,1], e.g. 0.5");

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { System.err.println(e.getMessage()); System.exit(2); }

When it happens

Trigger: applySimpleConfig (via toolInitialization/applyAll) with cassandra.yaml setting max_space_usable_for_compactions_in_percentage outside [0, 1].

Common situations: Operator writes 50 meaning 50% instead of the required 0.5; copy-paste from older docs or other tools that use percent (0-100) semantics.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Load CIDR groups cache operation not supported by %s
• Unsupported parameter '%s' for %s, supported parameters are
• JAAS login configuration missing for JMX authenticator setup
• repair_session_max_tree_depth should not be < 10, but was ${
• repair_session_space must be > 0, but was ${conf.repair_sess

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