apache/cassandra · error · IllegalArgumentException

Invalid throttle for snapshot_links_per_second: must be posi

Error message

Invalid throttle for snapshot_links_per_second: must be positive

What it means

Cassandra throws this IllegalArgumentException when setSnapshotLinksPerSecond is called with a negative throttle value. snapshot_links_per_second throttles the rate of hard-link creation during snapshots; negative values are meaningless and rejected.

Source

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

    {
        conf.auto_snapshot = autoSnapshot;
    }

    @VisibleForTesting
    public static boolean getAutoSnapshot()
    {
        return conf.auto_snapshot;
    }

    public static long getSnapshotLinksPerSecond()
    {
        return conf.snapshot_links_per_second == 0 ? Long.MAX_VALUE : conf.snapshot_links_per_second;
    }

    public static void setSnapshotLinksPerSecond(long throttle)
    {
        if (throttle < 0)
            throw new IllegalArgumentException("Invalid throttle for snapshot_links_per_second: must be positive");

        conf.snapshot_links_per_second = throttle;
    }

    public static RateLimiter getSnapshotRateLimiter()
    {
        return RateLimiter.create(getSnapshotLinksPerSecond());
    }

    public static boolean isAutoBootstrap()
    {
        return AUTO_BOOTSTRAP.getBoolean(conf.auto_bootstrap);
    }

    public static void setHintedHandoffEnabled(boolean hintedHandoffEnabled)
    {
        conf.hinted_handoff_enabled = hintedHandoffEnabled;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Pass a non-negative value; use 0 to disable throttling (Long.MAX_VALUE effective rate)
2. Validate the computed value before calling setSnapshotLinksPerSecond
3. If unlimited snapshots are intended, simply omit the setting instead of a sentinel negative

Example fix

// before
DatabaseDescriptor.setSnapshotLinksPerSecond(throttleFromConfig); // -5
// after
if (throttleFromConfig >= 0) DatabaseDescriptor.setSnapshotLinksPerSecond(throttleFromConfig);

if (throttle < 0) throw new IllegalArgumentException("snapshot_links_per_second must be >= 0 (0 = unlimited)");

try {
    DatabaseDescriptor.setSnapshotLinksPerSecond(throttle);
} catch (IllegalArgumentException e) {
    logger.warn("Rejected snapshot throttle, keeping current value", e);
}

When it happens

Trigger: Calling DatabaseDescriptor.setSnapshotLinksPerSecond(-1) or any negative long, typically via JMX (StorageService/ColumnFamilyStore snapshot rate limiter settings) or programmatic config mutation.

Common situations: Automation scripts computing the throttle from a formula that can go negative, or operators intending 0 (= unlimited) but entering a negative number.

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

• Invalid data rate: value must be non-negative
• Invalid data storage: %s Accepted units:%s
• snapshot_links_per_second must be >= 0
• Invalid value of entire_sstable_stream_throughput_outbound:
• Invalid value of entire_sstable_inter_dc_stream_throughput_o

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