apache/cassandra · error · IllegalArgumentException

native_transport_max_backoff_on_queue_overload should be…

Error message

native_transport_max_backoff_on_queue_overload should be greater than native_transport_min_backoff_on_queue_overload, but %s >= %s

What it means

setNativeTransportBackoffOnQueueOverload requires max backoff to be strictly greater than min backoff; passing minBackoffMillis >= maxBackoffMillis throws IllegalArgumentException with a formatted message showing both values.

Solutions

  1. Ensure maxBackoffMillis > minBackoffMillis
  2. Check argument order in the call (min first, then max)
  3. Re-read the values from the error message to see which was passed where

Example fix

// before
setNativeTransportBackoffOnQueueOverload(1000, 1000, TimeUnit.MILLISECONDS);
// after
setNativeTransportBackoffOnQueueOverload(100, 1000, TimeUnit.MILLISECONDS);
Defensive patterns

Strategy: validation

Validate before calling

if (minBackoffMillis >= maxBackoffMillis)
    throw new IllegalArgumentException("require min < max: " + minBackoffMillis + " >= " + maxBackoffMillis);

Try / catch

try {
    DatabaseDescriptor.setNativeTransportBackoffOnQueueOverload(min, max, unit);
} catch (IllegalArgumentException e) {
    // message contains both offending values; log and fall back to defaults
    logger.warn("Backoff range invalid: {}", e.getMessage());
}

Prevention

When it happens

Trigger: Calling setNativeTransportBackoffOnQueueOverload(min, max, unit) with min >= max (e.g. equal values or swapped arguments).

Common situations: Swapping min/max arguments at a call site; setting both to the same value assuming equality is allowed.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

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

            return native_transport_timeout_nanos_cached;
        }
        return conf.native_transport_timeout.to(timeUnit);

View on GitHub (pinned to 88fd0f6a0e)