apache/cassandra · error · org.apache.cassandra.exceptions.ConfigurationException

%s must be positive value <= %dB, but was %dB

Error message

%s must be positive value <= %dB, but was %dB

What it means

DatabaseDescriptor.checkValidForByteConversion validates that a memory setting expressed as a DataStorageSpec.IntKibibytesBound converts to a byte count in the range [0, Integer.MAX_VALUE - 1]. Out-of-range values produce a ConfigurationException naming the setting, the max, and the offending size.

Source

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

        commitLogSegmentMgrProvider = provider;
    }

    private static DataStorageSpec.IntKibibytesBound createIntKibibyteBoundAndEnsureItIsValidForByteConversion(int kibibytes, String propertyName)
    {
        DataStorageSpec.IntKibibytesBound intKibibytesBound = new DataStorageSpec.IntKibibytesBound(kibibytes);
        checkValidForByteConversion(intKibibytesBound, propertyName);
        return intKibibytesBound;
    }

    /**
     * Ensures passed in configuration value is positive and will not overflow when converted to Bytes
     */
    private static void checkValidForByteConversion(final DataStorageSpec.IntKibibytesBound value, String name)
    {
        long valueInBytes = value.toBytesInLong();
        if (valueInBytes < 0 || valueInBytes > Integer.MAX_VALUE - 1)
        {
            throw new ConfigurationException(String.format("%s must be positive value <= %dB, but was %dB",
                                                           name,
                                                           Integer.MAX_VALUE - 1,
                                                           valueInBytes),
                                             false);
        }
    }

    public static int getValidationPreviewPurgeHeadStartInSec()
    {
        return conf.validation_preview_purge_head_start.toSeconds();
    }

    public static boolean checkForDuplicateRowsDuringReads()
    {
        return conf.check_for_duplicate_rows_during_reads;
    }

    public static void setCheckForDuplicateRowsDuringReads(boolean enabled)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Reduce the value so its byte size is <= Integer.MAX_VALUE - 1 (under 2GiB)
2. Fix the storage unit (KiB/MiB/GiB) so the byte conversion lands in range
3. Correct a negative value in the config file

Example fix

// before
max_value_size: 8GiB  # exceeds int byte bound
// after
max_value_size: 2GiB  # or smaller

long bytes = storageSpec.toBytesInLong(); if (bytes < 0 || bytes > Integer.MAX_VALUE - 1L) throw new IllegalArgumentException(name + " must be in [0, 2147483647] bytes");

try { DatabaseDescriptor.applySimpleConfig(...); } catch (ConfigurationException e) { logger.error("memory setting out of int byte range: {}", e.getMessage()); }

When it happens

Trigger: Setting a cassandra config byte-bounded option (e.g. max_mutation_size_in_kb style DataStorageSpec fields) whose byte value is negative or exceeds Integer.MAX_VALUE - 1 (2147483647 bytes ~2GiB).

Common situations: Configuring values above 2GiB for options that must fit an int-sized byte bound, or unit mistakes (GiB vs KiB) producing negative/oversized byte conversions.

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

• memtable_heap_space must be positive, but was ${conf.memtabl
• Invalid data storage: ${value}. It shouldn't be more than ${
• Invalid data storage: %d %s. It shouldn't be more than %d in
• Invalid value of auto_snapshot_ttl: ${conf.auto_snapshot_ttl
• Missing value for commitlog_sync_group_window.

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