apache/cassandra · error · ConfigurationException

entire_sstable_stream_throughput_outbound

Error message

entire_sstable_stream_throughput_outbound: %s is too large

What it means

Guard on the entire-sstable streaming throttle: if cassandra.yaml sets entire_sstable_stream_throughput_outbound to a rate converting to >= Integer.MAX_VALUE mebibytes per second, LoaderOptions.Builder throws ConfigurationException 'entire_sstable_stream_throughput_outbound: <value> is too large'. See tools/sstableloader/src/org/apache/cassandra/tools/LoaderOptions.java:508.

Solutions

Set entire_sstable_stream_throughput_outbound to a sane value (e.g. 0 to disable) in cassandra.yaml
Remove the key entirely if you don't intend to throttle entire-sstable streaming
Confirm the loaded config is the one you expect via --conf-path

Example fix

// before (cassandra.yaml)
entire_sstable_stream_throughput_outbound: 99999999999MiB/s
// after
entire_sstable_stream_throughput_outbound: 0MiB/s

Defensive patterns

Strategy: validation

Validate before calling

// pre-check config
// grep entire_sstable_stream_throughput_outbound $CONF/cassandra.yaml
// value should be a sane MiB/s rate or 0/null to disable

Try / catch

try {
    options = new LoaderOptions.Builder(dirs, args).build();
} catch (ConfigurationException e) {
    if (e.getMessage().startsWith("entire_sstable_stream_throughput_outbound")) {
        // fix the yaml value and retry
    }
    throw e;
}

Prevention

Keep entire-sstable throttle values small and unit-correct (MiB/s)
Remove keys you don't intend to configure rather than setting extreme defaults
Review machine-generated configs before loading with sstableloader
Test against a staging config first

When it happens

Trigger: sstableloader reading a config where entire_sstable_stream_throughput_outbound exceeds the int bound in MiB/s — practically only from hand-editing mistakes or generated configs with bad values.

Common situations: Scripts inserting placeholder/extreme values; pasted values without unit awareness; older yamls merged with newer config keys.

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

Appendix: source

Thrown at tools/sstableloader/src/org/apache/cassandra/tools/LoaderOptions.java:508

                    {
                        errorMsg("Config file not found", options);
                    }
                    config = new YamlConfigurationLoader().loadConfig(configFile.toPath().toUri().toURL());

                    // below 2 checks are needed in order to match the pre-CASSANDRA-15234 upper bound for those parameters which were still in megabits per second
                    if (config.stream_throughput_outbound.toMegabitsPerSecond() >= Integer.MAX_VALUE)
                    {
                        throw new ConfigurationException("stream_throughput_outbound: " + config.stream_throughput_outbound.toString() + " is too large", false);
                    }

                    if (config.inter_dc_stream_throughput_outbound.toMegabitsPerSecond() >= Integer.MAX_VALUE)
                    {
                        throw new ConfigurationException("inter_dc_stream_throughput_outbound: " + config.inter_dc_stream_throughput_outbound.toString() + " is too large", false);
                    }

                    if (config.entire_sstable_stream_throughput_outbound.toMebibytesPerSecond() >= Integer.MAX_VALUE)
                    {
                        throw new ConfigurationException("entire_sstable_stream_throughput_outbound: " + config.entire_sstable_stream_throughput_outbound.toString() + " is too large", false);
                    }

                    if (config.entire_sstable_inter_dc_stream_throughput_outbound.toMebibytesPerSecond() >= Integer.MAX_VALUE)
                    {
                        throw new ConfigurationException("entire_sstable_inter_dc_stream_throughput_outbound: " + config.entire_sstable_inter_dc_stream_throughput_outbound.toString() + " is too large", false);
                    }
                }
                else
                {
                    config = new Config();
                    // unthrottle stream by default
                    config.stream_throughput_outbound = new DataRateSpec.LongBytesPerSecondBound(0);
                    config.inter_dc_stream_throughput_outbound = new DataRateSpec.LongBytesPerSecondBound(0);
                    config.entire_sstable_stream_throughput_outbound = new DataRateSpec.LongBytesPerSecondBound(0);
                    config.entire_sstable_inter_dc_stream_throughput_outbound = new DataRateSpec.LongBytesPerSecondBound(0);
                }

                if (cmd.hasOption(STORAGE_PORT_OPTION))

View on GitHub (pinned to 88fd0f6a0e)