apache/cassandra · error · ConfigurationException

max_value_size must be positive

Error message

max_value_size must be positive

What it means

max_value_size bounds the size of a single column value that Cassandra will accept. DatabaseDescriptor throws this ConfigurationException when the configured value rounds down to 0 MiB, because a zero maximum would reject every write.

Solutions

1. Set max_value_size_in_bytes to at least 1048576 (1 MiB)
2. Keep it below 2048 MiB to satisfy the companion upper-bound check
3. Remove the override to use the default (256 MiB)

Example fix

# before (cassandra.yaml)
max_value_size_in_bytes: 512000
# after
max_value_size_in_bytes: 16777216

long valueBytes = conf.max_value_size.toBytes();
if (valueBytes == 0 || valueBytes < 1024L * 1024L) throw new IllegalArgumentException("max_value_size must be >= 1 MiB");

try { DatabaseDescriptor.applyConfig(conf); } catch (ConfigurationException e) { if (e.getMessage().contains("max_value_size must be positive")) { /* raise the value */ } }

When it happens

Trigger: cassandra.yaml sets max_value_size_in_bytes (max_value_size) to a value below 1 MiB (or 0) and DatabaseDescriptor.applySimpleConfig runs; note the check is on toMebibytes(), so anything under 1MiB is treated as 0.

Common situations: Setting max_value_size_in_bytes to a small byte count like 1024 expecting byte-precision; clearing the value to 0 intending 'unlimited'; template rendering an unset variable as 0.

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

• max_value_size must be smaller than 2048, but was
• A maximum number of tokens per node is supported
• accord.cache_size option was set incorrectly to
• accord.journal_directory must not be the same as any…
• Allowing java.lang.System.* access in UDFs is dangerous and…

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

Appendix: source

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

        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)
            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)

View on GitHub (pinned to 88fd0f6a0e)