apache/cassandra · error · ConfigurationException

native_transport_max_frame_size must be positive value < %dB

Q: What causes "native_transport_max_frame_size must be positive value < %dB, but was %dB" in apache/cassandra?

Set native_transport_max_frame_size to a positive value below 2147483647 bytes (e.g. 256MiB)

Error message

native_transport_max_frame_size must be positive value < %dB, but was %dB

What it means

native_transport_max_frame_size limits the size of frames the CQL native protocol will accept. It must fit in a positive signed int (0 < value <= Integer.MAX_VALUE - 1 = 2147483647 bytes). Validation in applySimpleConfig throws ConfigurationException (ignorable=false) so the node will not start with an out-of-range frame size.

Source

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

        else
        {
            conf.repair_session_max_tree_depth = 20;
        }

        if (conf.repair_session_space == null)
            conf.repair_session_space = new DataStorageSpec.IntMebibytesBound(Math.max(1, (int) (Runtime.getRuntime().maxMemory() / (16 * 1048576))));

        if (conf.repair_session_space.toMebibytes() < 1)
            throw new ConfigurationException("repair_session_space must be > 0, but was " + conf.repair_session_space);
        else if (conf.repair_session_space.toMebibytes() > (int) (Runtime.getRuntime().maxMemory() / (4 * 1048576)))
            logger.warn("A repair_session_space of " + conf.repair_session_space + " mebibytes is likely to cause heap pressure");

        checkForLowestAcceptedTimeouts(conf);

        long valueInBytes = conf.native_transport_max_frame_size.toBytes();
        if (valueInBytes < 0 || valueInBytes > Integer.MAX_VALUE - 1)
        {
            throw new ConfigurationException(String.format("native_transport_max_frame_size must be positive value < %dB, but was %dB",
                                                           Integer.MAX_VALUE,
                                                           valueInBytes),
                                             false);
        }

        if (conf.column_index_size != null)
            checkValidForByteConversion(conf.column_index_size, "column_index_size");
        checkValidForByteConversion(conf.column_index_cache_size, "column_index_cache_size");
        checkValidForByteConversion(conf.batch_size_warn_threshold, "batch_size_warn_threshold");

        // if data dirs, commitlog dir, or saved caches dir are set in cassandra.yaml, use that.  Otherwise,
        // use -Dcassandra.storagedir (set in cassandra-env.sh) as the parent dir for data/, commitlog/, and saved_caches/
        if (conf.commitlog_directory == null)
        {
            conf.commitlog_directory = storagedirFor("commitlog");
        }

        initializeCommitLogDiskAccessMode();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set native_transport_max_frame_size to a positive value below 2147483647 bytes (e.g. 256MiB)
Reduce oversized values like 4GiB to something <= Integer.MAX_VALUE - 1
If large payloads are needed, use paging/batching within protocol limits instead of raising frame size

Example fix

// before (cassandra.yaml)
native_transport_max_frame_size: 4GiB
// after (cassandra.yaml)
native_transport_max_frame_size: 256MiB

Defensive patterns

Strategy: validation

Validate before calling

long bytes = conf.native_transport_max_frame_size.toBytes();
if (bytes <= 0 || bytes > Integer.MAX_VALUE - 1)
    throw new IllegalArgumentException("native_transport_max_frame_size must be 0 < bytes < 2147483648, got " + bytes);

Try / catch

try {
    DatabaseDescriptor.toolInitialization();
} catch (ConfigurationException e) {
    if (e.getMessage().contains("native_transport_max_frame_size"))
        throw new StartupConfigError("frame size must fit in a positive int", e);
    throw e;
}

Prevention

Keep native_transport_max_frame_size well under 2GiB (e.g. 256MiB)
Never set 0 or negative frame sizes
Handle large payloads with paging instead of frame-size increases

When it happens

Trigger: Setting native_transport_max_frame_size to a negative value, 0, or >= 2GB (e.g. '4GiB') in cassandra.yaml; validated whenever DatabaseDescriptor is initialized.

Common situations: Operators raising the frame size to accommodate large batch inserts who set it to 4GiB or higher; unit-suffix mistakes; configs copied from third-party tuning guides.

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