apache/cassandra · error · IllegalArgumentException

Invalid value for data_disk_usage_max_disk_size

Error message

Invalid value for data_disk_usage_max_disk_size: %s specified, but only %s are actually available on disk

What it means

validateDataDiskUsageMaxDiskSize compares the configured data_disk_usage_max_disk_size with the actual total disk space reported by DiskUsageMonitor.totalDiskSpace(). If the configured size exceeds the physically available space, the percentage thresholds would be unattainable, so IllegalArgumentException is thrown listing specified vs. available sizes.

Solutions

Set data_disk_usage_max_disk_size to a value <= actual total disk space (check with df / FileUtils.stringifyFileSize of total).
Leave the value empty so guardrails use real disk capacity.
Use per-node config templating so large-node values aren't applied to smaller nodes.

Example fix

// before
data_disk_usage_max_disk_size: 10TiB
// after
data_disk_usage_max_disk_size: 1TiB

Defensive patterns

Strategy: validation

Validate before calling

long total = DiskUsageMonitor.totalDiskSpace();
if (maxDiskSize != null && maxDiskSize.toBytes() > total)
    throw new IllegalArgumentException("configured max disk size exceeds available " + FileUtils.stringifyFileSize(total));

Try / catch

try { options.validate(); } catch (IllegalArgumentException e) { LOG.error("max disk size exceeds real capacity: {}", e.getMessage()); }

Prevention

Verify total disk capacity on the target node before configuring an absolute max size
Prefer leaving data_disk_usage_max_disk_size empty so percentages use real capacity
Template per-node config when disks differ across the cluster

When it happens

Trigger: Setting data_disk_usage_max_disk_size larger than the node's actual total disk capacity at config-validation time (e.g. '10TiB' on a 2TiB disk), either in cassandra.yaml or programmatically.

Common situations: Copying config from a larger machine; using a shared cassandra.yaml across heterogeneous nodes; volumes mounted or resized after the config was written; small CI/dev machines running a production config.

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

Appendix: source

Thrown at src/java/org/apache/cassandra/config/GuardrailsOptions.java:1687

            throw new IllegalArgumentException(format("Invalid value for %s: null is not allowed", name));

        return consistencyLevels.isEmpty() ? Collections.emptySet() : Sets.immutableEnumSet(consistencyLevels);
    }

    private static void validateDataDiskUsageMaxDiskSize(DataStorageSpec.LongBytesBound maxDiskSize)
    {
        if (maxDiskSize == null)
            return;

        // Unlike a guardrail threshold, this is the disk size the percentage thresholds are calculated against, so zero is meaningless
        if (maxDiskSize.toBytes() == 0)
            throw new IllegalArgumentException("Invalid value for data_disk_usage_max_disk_size: 0 is not allowed; " +
                                               "if attempting to disable use an empty value");

        long diskSize = DiskUsageMonitor.totalDiskSpace();

        if (diskSize < maxDiskSize.toBytes())
            throw new IllegalArgumentException(format("Invalid value for data_disk_usage_max_disk_size: " +
                                                      "%s specified, but only %s are actually available on disk",
                                                      maxDiskSize, FileUtils.stringifyFileSize(diskSize)));
    }

    /**
     * This method tests not only valid configuration, but also that what we generate with
     * a generator passes its validator, so we avoid the situation when a configuration would be valid according
     * to a concrete implementation of a password validator but passwords it would generate would not pass
     * its validator which is clearly not desired.
     *
     * @param config configuration to use for generator and validator
     */
    private static void validatePasswordPolicy(CustomGuardrailConfig config)
    {
        ValueGenerator.getGenerator("password_policy", config).generate(ValueValidator.getValidator("password_policy", config), Map.of());
    }

    private static void validateRoleNamePolicy(CustomGuardrailConfig config)

View on GitHub (pinned to 88fd0f6a0e)