What causes "Threshold must be less than Integer.MAX_VALUE" in apache/cassandra?

Q: What causes "Threshold must be less than Integer.MAX_VALUE" in apache/cassandra?

Pass a threshold <= Integer.MAX_VALUE milliseconds (about 24.8 days)

apache/cassandra · error · java.lang.IllegalArgumentException

Threshold must be less than Integer.MAX_VALUE

Error message

Threshold must be less than Integer.MAX_VALUE

What it means

DatabaseDescriptor.setGCWarnThreshold validates the gc_warn_threshold value. Any value above Integer.MAX_VALUE is rejected because the threshold is internally stored/compared against millisecond bounds that must fit an int-sized range. The caller passed a long that exceeds the allowed maximum.

Solutions

Pass a threshold <= Integer.MAX_VALUE milliseconds (about 24.8 days)
Use 0 to disable the warn threshold
Fix the unit conversion so the value is expressed in milliseconds
Clamp the value before calling: Math.min(threshold, Integer.MAX_VALUE)

Example fix

// before
DatabaseDescriptor.setGCWarnThreshold(60_000_000_000L); // ns for 60s
// after
DatabaseDescriptor.setGCWarnThreshold(60_000L); // ms for 60s

Defensive patterns

Strategy: validation

Validate before calling

if (thresholdMs < 0 || thresholdMs > Integer.MAX_VALUE) throw new IllegalArgumentException("gc_warn_threshold must be in [0, Integer.MAX_VALUE] ms");

Try / catch

try { DatabaseDescriptor.setGCWarnThreshold(v); } catch (IllegalArgumentException e) { logger.error("invalid gc_warn_threshold: {}", e.getMessage()); }

Prevention

Express all GC thresholds in milliseconds before calling setters
Clamp to Integer.MAX_VALUE when converting from other units
Test config parsing with boundary values

When it happens

Trigger: Calling setGCWarnThreshold(threshold) with a threshold > Integer.MAX_VALUE (2147483647 ms), e.g. passing a value in nanoseconds/microseconds by mistake, or a Long.MAX_VALUE sentinel.

Common situations: Unit conversion mistakes (seconds vs ms vs ns) when setting GC warn thresholds programmatically or via a config loader that does not pre-clamp values.

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

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

Appendix: source

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

    public static EncryptionContext getEncryptionContext()
    {
        return encryptionContext;

    }

    public static long getGCWarnThreshold()
    {
        return conf.gc_warn_threshold.toMilliseconds();
    }

    public static void setGCWarnThreshold(long threshold)
    {
        if (threshold < 0)
            throw new IllegalArgumentException("Threshold value for gc_warn_threshold must be greater than or equal to 0");

        if (threshold > Integer.MAX_VALUE)
            throw new IllegalArgumentException("Threshold must be less than Integer.MAX_VALUE");

        long gcLogThresholdInMs = getGCLogThreshold();
        if (threshold != 0 && threshold <= gcLogThresholdInMs)
            throw new IllegalArgumentException("Threshold value for gc_warn_threshold (" + threshold + ") must be greater than gc_log_threshold which is currently "
                                               + gcLogThresholdInMs);

        conf.gc_warn_threshold = new DurationSpec.IntMillisecondsBound(threshold);
    }

    public static int getGCConcurrentPhaseLogThreshold()
    {
        return conf.gc_concurrent_phase_log_threshold.toMilliseconds();
    }

    public static void setGCConcurrentPhaseLogThreshold(int threshold)
    {
        if (threshold <= 0)
            throw new IllegalArgumentException("Threshold must be greater than 0");

View on GitHub (pinned to 88fd0f6a0e)