What causes "snapshot_links_per_second must be >= 0" in apache/cassandra?

Set snapshot_links_per_second to 0 (or omit it) to disable rate limiting

apache/cassandra · error · ConfigurationException

snapshot_links_per_second must be >= 0

Error message

snapshot_links_per_second must be >= 0

What it means

snapshot_links_per_second rate-limits hard-link creation during snapshots (null-device/snapshot throttling). DatabaseDescriptor rejects negative values at startup with this ConfigurationException, since a negative link rate is meaningless.

Source

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

        if (conf.client_encryption_options != null)
            conf.client_encryption_options.applyConfig();

        if (conf.jmx_server_options == null)
        {
            conf.jmx_server_options = JMXServerOptions.createParsingSystemProperties();
        }
        else if (JMXServerOptions.isEnabledBySystemProperties())
        {
                throw new ConfigurationException("Configure either jmx_server_options in cassandra.yaml and comment out " +
                                                 "configure_jmx function call in cassandra-env.sh or keep cassandra-env.sh " +
                                                 "to call configure_jmx function but you have to keep jmx_server_options " +
                                                 "in cassandra.yaml commented out.");
        }

        conf.jmx_server_options.jmx_encryption_options.applyConfig();

        if (conf.snapshot_links_per_second < 0)
            throw new ConfigurationException("snapshot_links_per_second must be >= 0");

        if (conf.max_value_size.toMebibytes() == 0)
            throw new ConfigurationException("max_value_size must be positive", false);
        else if (conf.max_value_size.toMebibytes() >= 2048)
            throw new ConfigurationException("max_value_size must be smaller than 2048, but was "
                                             + conf.max_value_size.toString(), false);

        switch (conf.disk_optimization_strategy)
        {
            case ssd:
                diskOptimizationStrategy = new SsdDiskOptimizationStrategy(conf.disk_optimization_page_cross_chance);
                break;
            case spinning:
                diskOptimizationStrategy = new SpinningDiskOptimizationStrategy();
                break;
        }

        if (conf.compressed_read_ahead_buffer_size.toKibibytes() > 0 && conf.compressed_read_ahead_buffer_size.toKibibytes() < 256)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set snapshot_links_per_second to 0 (or omit it) to disable rate limiting
Set it to a positive integer appropriate for your filesystem

Example fix

# before (cassandra.yaml)
snapshot_links_per_second: -10
# after
snapshot_links_per_second: 0

Defensive patterns

Strategy: validation

Validate before calling

if (conf.snapshot_links_per_second < 0) throw new IllegalArgumentException("snapshot_links_per_second must be >= 0");

Try / catch

try { DatabaseDescriptor.applyConfig(conf); } catch (ConfigurationException e) { if (e.getMessage().startsWith("snapshot_links_per_second")) { /* fix the yaml value */ } }

Prevention

Use 0 to disable snapshot link throttling rather than negative numbers
Template-render configs with explicit defaults so unset variables never become -1
Lint cassandra.yaml numeric fields for non-negativity

When it happens

Trigger: cassandra.yaml sets snapshot_links_per_second to a negative number and DatabaseDescriptor.applySimpleConfig runs during startup/configuration load.

Common situations: Typo or accidental minus sign when tuning snapshot throttling; templating bug that substitutes an empty/placeholder value with '-1'; copying a partial line from a tuning guide.

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/f99b3f321743e0eb. Report an issue: GitHub.