What causes "max_value_size must be smaller than 2048, but was " in apache/cassandra?

Set max_value_size_in_bytes to less than 2147483648 bytes (e.g. 2097152000 for ~2000 MiB)

apache/cassandra · error · ConfigurationException

max_value_size must be smaller than 2048, but was

Error message

max_value_size must be smaller than 2048, but was <value>

What it means

max_value_size must stay below 2048 MiB because values are read through a bounded buffer whose addressing is limited to 2GB. DatabaseDescriptor throws this ConfigurationException, including the offending value in the message, when max_value_size.toMebibytes() >= 2048.

Solutions

Set max_value_size_in_bytes to less than 2147483648 bytes (e.g. 2097152000 for ~2000 MiB)
Split oversized payloads into multiple values or use external blob storage with references
Remove the override to use the default

Example fix

# before (cassandra.yaml)
max_value_size_in_bytes: 2147483648
# after
max_value_size_in_bytes: 2097152000

Defensive patterns

Strategy: validation

Validate before calling

if (conf.max_value_size.toMebibytes() >= 2048) throw new IllegalArgumentException("max_value_size must be < 2048 MiB");

Try / catch

try { DatabaseDescriptor.applyConfig(conf); } catch (ConfigurationException e) { if (e.getMessage().contains("smaller than 2048")) { /* clamp value below 2GiB */ } }

Prevention

Treat 2048 MiB as an exclusive upper bound (max allowed is 2047 MiB)
Do not copy internode message-size values into max_value_size
Use external blob storage instead of trying to raise limits beyond 2GiB

When it happens

Trigger: cassandra.yaml sets max_value_size_in_bytes (or max_value_size) to 2048 MiB or more (e.g. 2147483648 bytes or '2g' or larger) and DatabaseDescriptor.applySimpleConfig runs at startup.

Common situations: Operators trying to admit huge blobs by setting 2g/4g; misunderstanding that 2048 is exclusive so the max allowed is just under 2048 MiB; copy-paste of max_message_size-like values into max_value_size.

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

Appendix: source

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

            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)
            throw new ConfigurationException("compressed_read_ahead_buffer_size must be at least 256KiB (set to 0 to disable), but was " + conf.compressed_read_ahead_buffer_size, false);

        if (conf.server_encryption_options != null)
        {
            conf.server_encryption_options.applyConfig();

View on GitHub (pinned to 88fd0f6a0e)