apache/cassandra · error · ConfigurationException

native_transport_min_backoff_on_queue_overload should be str

Error message

native_transport_min_backoff_on_queue_overload should be strictly less than native_transport_max_backoff_on_queue_overload, but %s >= %s

What it means

The native transport backoff range must be ordered: min must be strictly less than max. DatabaseDescriptor throws this ConfigurationException when native_transport_min_backoff_on_queue_overload >= native_transport_max_backoff_on_queue_overload.

Source

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

        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));
        }

        if (conf.native_transport_min_backoff_on_queue_overload.toMilliseconds() <= 0)
            throw new ConfigurationException(" be positive");

        if (conf.native_transport_min_backoff_on_queue_overload.toMilliseconds() >= conf.native_transport_max_backoff_on_queue_overload.toMilliseconds())
            throw new ConfigurationException(String.format("native_transport_min_backoff_on_queue_overload should be strictly less than native_transport_max_backoff_on_queue_overload, but %s >= %s",
                                                           conf.native_transport_min_backoff_on_queue_overload,
                                                           conf.native_transport_max_backoff_on_queue_overload));

        if (conf.use_deterministic_table_id)
            logger.warn("use_deterministic_table_id is no longer supported and should be removed from cassandra.yaml.");

        // run audit logging options through sanitation and validation
        if (conf.audit_logging_options != null)
            setAuditLoggingOptions(conf.audit_logging_options);

        try
        {
            // Run through the validation by setting current values back to their setters, so we are sure that their values are valid.
            // We are catching IllegalArgumentException and translating it to ConfigurationException to comply with
            // rest of the logic in this method. These setters are also called in GCInspectorMXBean were IllegalArgumentException
            // is thrown when arguments are invalid instead ConfigurationException, on purpose.
            DatabaseDescriptor.setGCLogThreshold((int) DatabaseDescriptor.getGCLogThreshold());
            DatabaseDescriptor.setGCWarnThreshold((int) DatabaseDescriptor.getGCWarnThreshold());

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set native_transport_max_backoff_on_queue_overload strictly greater than native_transport_min_backoff_on_queue_overload
Lower native_transport_min_backoff_on_queue_overload below the max value
Verify both durations use consistent units

Example fix

// before (cassandra.yaml)
native_transport_min_backoff_on_queue_overload: 500ms
native_transport_max_backoff_on_queue_overload: 500ms
// after
native_transport_min_backoff_on_queue_overload: 100ms
native_transport_max_backoff_on_queue_overload: 500ms

Defensive patterns

Strategy: validation

Validate before calling

if (conf.native_transport_min_backoff_on_queue_overload.toMilliseconds() >= conf.native_transport_max_backoff_on_queue_overload.toMilliseconds()) throw new IllegalArgumentException("min backoff must be strictly less than max backoff");

Try / catch

try { DatabaseDescriptor.toolInitialization(); } catch (ConfigurationException e) { log.error(e.getMessage()); System.exit(1); }

Prevention

Treat (min, max) backoff as a strict interval; max > min always
Use consistent units for both settings
Review pairs of related config keys together

When it happens

Trigger: applySimpleConfig (via toolInitialization/applyAll) with min backoff >= max backoff (equal values included).

Common situations: Setting both values equal; raising min above max while tuning queue-overload behavior; unit mismatch making min evaluate larger than max.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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