apache/cassandra · error · IllegalArgumentException

native_transport_min_backoff_on_queue_overload should be…

Error message

native_transport_min_backoff_on_queue_overload should be positive

What it means

setNativeTransportBackoffOnQueueOverload validates the minimum backoff applied to clients when the native transport queue is overloaded; a non-positive minBackoffMillis throws IllegalArgumentException because the backoff must be positive.

Solutions

Pass a positive value for minBackoffMillis (e.g. 10ms)
Ensure maxBackoffMillis is strictly greater than minBackoffMillis
If tuning via JMX, resend with corrected parameters

Example fix

// before
DatabaseDescriptor.setNativeTransportBackoffOnQueueOverload(0, 1000, TimeUnit.MILLISECONDS);
// after
DatabaseDescriptor.setNativeTransportBackoffOnQueueOverload(10, 1000, TimeUnit.MILLISECONDS);

Defensive patterns

Strategy: validation

Validate before calling

if (minBackoffMillis <= 0)
    throw new IllegalArgumentException("min backoff must be > 0 before calling setNativeTransportBackoffOnQueueOverload");

Try / catch

try {
    DatabaseDescriptor.setNativeTransportBackoffOnQueueOverload(min, max, TimeUnit.MILLISECONDS);
} catch (IllegalArgumentException e) {
    logger.warn("Rejecting backoff config: {}", e.getMessage());
}

Prevention

Clamp min backoff to at least 1ms before setting
Enforce min < max at the caller side
Unit-test setter wrappers with boundary values

When it happens

Trigger: Calling DatabaseDescriptor.setNativeTransportBackoffOnQueueOverload with minBackoffMillis <= 0; setting native_transport_min_backoff_on_queue_overload to 0 or negative via JMX or config validation.

Common situations: Operators trying to disable backoff by setting min to 0; scripted JMX calls with wrong units or typo'd values.

Related errors

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

Appendix: source

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

        conf.native_transport_queue_max_item_age_threshold = threshold;
    }

    public static long getNativeTransportMinBackoffOnQueueOverload(TimeUnit timeUnit)
    {
        return conf.native_transport_min_backoff_on_queue_overload.to(timeUnit);
    }

    public static long getNativeTransportMaxBackoffOnQueueOverload(TimeUnit timeUnit)
    {
        return conf.native_transport_max_backoff_on_queue_overload.to(timeUnit);
    }

    public static void setNativeTransportBackoffOnQueueOverload(long minBackoffMillis,
                                                                long maxBackoffMillis,
                                                                TimeUnit timeUnit)
    {
        if (minBackoffMillis <= 0)
            throw new IllegalArgumentException("native_transport_min_backoff_on_queue_overload should be positive");

        if (minBackoffMillis >= maxBackoffMillis)
            throw new IllegalArgumentException(String.format("native_transport_max_backoff_on_queue_overload should be greater than native_transport_min_backoff_on_queue_overload, but %s >= %s", minBackoffMillis, maxBackoffMillis));


        conf.native_transport_min_backoff_on_queue_overload = new DurationSpec.LongMillisecondsBound(minBackoffMillis, timeUnit);
        conf.native_transport_max_backoff_on_queue_overload = new DurationSpec.LongMillisecondsBound(maxBackoffMillis, timeUnit);
    }

    private static long native_transport_timeout_nanos_cached = -1;

    public static long getNativeTransportTimeout(TimeUnit timeUnit)
    {
        if (timeUnit == TimeUnit.NANOSECONDS)
        {
            if (native_transport_timeout_nanos_cached == -1)
                native_transport_timeout_nanos_cached = conf.native_transport_timeout.to(TimeUnit.NANOSECONDS);

View on GitHub (pinned to 88fd0f6a0e)