apache/cassandra · error · IllegalArgumentException

Threshold value for gc_warn*_threshold must be greater than

Error message

Threshold value for gc_warn*_threshold must be greater than 0

What it means

Cassandra throws this IllegalArgumentException from validateGCParams when the GC warn threshold (gc_warn_threshold) is zero or negative. This threshold controls when a GC pause is logged at WARN level and must be a positive millisecond value (0 is special-cased only downstream, not here).

Source

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

    {
        return conf.gc_log_threshold.toMilliseconds();
    }

    public static void setGCLogThreshold(int threshold)
    {
        validateGCParams(threshold, getGCWarnThreshold());
        conf.gc_log_threshold = new DurationSpec.IntMillisecondsBound(threshold);
    }

    public static void validateGCParams(long logThreshold, long warnThreshold)
    {
        if (logThreshold <= 0)
            throw new IllegalArgumentException("Threshold value for gc_log*_threshold must be greater than 0");
        if (logThreshold > Integer.MAX_VALUE)
            throw new IllegalArgumentException("Threshold value for gc_log*_threshold must be less than Integer.MAX_VALUE");

        if (warnThreshold <= 0)
            throw new IllegalArgumentException("Threshold value for gc_warn*_threshold must be greater than 0");
        if (warnThreshold > Integer.MAX_VALUE)
            throw new IllegalArgumentException("Threshold value for gc_warn*_threshold must be less than Integer.MAX_VALUE");

        if (warnThreshold != 0 && logThreshold > warnThreshold)
            throw new IllegalArgumentException("Threshold value for gc_log*_threshold (" + logThreshold + ") must be less than gc_warn*_threshold which is currently "
                    + warnThreshold);
    }

    public static EncryptionContext getEncryptionContext()
    {
        return encryptionContext;

    }

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

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set gc_warn_threshold to a positive value larger than gc_log_threshold (e.g. 1000ms)
Remove a 0/negative gc_warn_threshold from cassandra.yaml
If warning suppression is truly needed, set it very high but under Integer.MAX_VALUE

Example fix

// before (cassandra.yaml)
gc_warn_threshold: 0ms
// after
gc_warn_threshold: 1000ms

Defensive patterns

Strategy: validation

Validate before calling

if (warnThreshold <= 0 || warnThreshold > Integer.MAX_VALUE)
    throw new IllegalArgumentException("gc_warn_threshold must be > 0 and <= Integer.MAX_VALUE ms");

Try / catch

try {
    DatabaseDescriptor.validateGCParams(logThreshold, warnThreshold);
} catch (IllegalArgumentException e) {
    logger.error("Invalid gc_warn_threshold", e);
}

Prevention

Keep gc_warn_threshold positive (default 1000ms)
To effectively silence warnings use a large but in-range value
Validate both thresholds together with validateGCParams

When it happens

Trigger: Calling validateGCParams(logThreshold, warnThreshold) with warnThreshold <= 0, or startup validation when gc_warn_threshold in cassandra.yaml is 0 or negative.

Common situations: Operators setting gc_warn_threshold: 0 to disable warnings; the startup validator rejects it here even though the runtime comparison code treats 0 as disabled.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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