apache/cassandra · error · ConfigurationException

Invalid value for system property: expected size in bytes wi

Error message

Invalid value for system property: expected size in bytes with unit but got '%s'

What it means

Cassandra system properties that map to byte-size values are parsed by a converter that calls FBUtilities.parseHumanReadableBytes. When the property value cannot be parsed as a human-readable byte size (e.g. '4GiB', '64m'), a ConfigurationException is thrown wrapping the original message and the offending value. It is raised at class-init/property-read time, so it typically fails fast at startup.

Source

Thrown at src/java/org/apache/cassandra/config/CassandraRelevantProperties.java:1137

        {
            return Long.decode(value);
        }
        catch (NumberFormatException e)
        {
            throw new ConfigurationException(String.format("Invalid value for system property: " +
                                                           "expected long value but got '%s'", value));
        }
    };

    private static final PropertyConverter<Long> SIZE_IN_BYTES_CONVERTER = value ->
    {
        try
        {
            return FBUtilities.parseHumanReadableBytes(value);
        }
        catch (ConfigurationException e)
        {
            throw new ConfigurationException(String.format("Invalid value for system property: " +
                                                           "expected size in bytes with unit but got '%s'\n%s", value, e));
        }
    };

    private static final PropertyConverter<Double> DOUBLE_CONVERTER = value ->
    {
        try
        {
            return Double.parseDouble(value);
        }
        catch (NumberFormatException e)
        {
            throw new ConfigurationException(String.format("Invalid value for system property: " +
                                                           "expected floating point value but got '%s'", value));
        }
    };

    /**

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Correct the system property value to a valid human-readable byte size with unit, e.g. 64MiB, 512MiB, 2GiB
  2. Check the full ConfigurationException message (the '%s' suffix includes the underlying parse error) for the exact parse failure
  3. Search jvm*.options, cassandra-env.sh and CASSANDRA_* env var exports for the property and fix the typo
  4. If a bare number was intended as bytes, append an explicit unit such as B (e.g. 1024B) if the parser accepts it

Example fix

// before
JVM_OPTS="$JVM_OPTS -Dcassandra.available_processors=16gb"
// after
JVM_OPTS="$JVM_OPTS -Dcassandra.request_timeout=16000ms"
// or for a bytes-valued property:
// before: -Dsome.bytes.prop=64g
// after:  -Dsome.bytes.prop=64GiB
Defensive patterns

Strategy: validation

Validate before calling

String v = System.getProperty("my.bytes.prop", "");
if (!v.matches("\\d+(B|KB|KiB|MB|MiB|GB|GiB|TB|TiB)"))
    throw new IllegalArgumentException("Property my.bytes.prop must be a size with unit, got: " + v);

Try / catch

try {
    prop.getString();
} catch (ConfigurationException e) {
    logger.error("Bad system property value, using default", e);
    value = DEFAULT_BYTES;
}

Prevention

When it happens

Trigger: Setting a Cassandra relevant system property (via -D JVM flags or System.setProperty) whose converter is BYTES_CONVERTER to a value without a recognized size unit or with garbage characters, e.g. -Dcassandra....=1024xyz or =64 gb with a space/typo.

Common situations: Hand-edited jvm-server.options or cassandra-env.sh entries; typos in unit suffixes (missing 'B', wrong case rules); copy-pasting values from docs of other tools that accept bare numbers or different unit spellings; setting the property in an environment where another agent appends stray whitespace.

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