apache/cassandra · error · ConfigurationException

Scaling parameter %s must match %s

Error message

Scaling parameter %s must match %s

What it means

UnifiedCompactionStrategy.parseScalingParameter validates the scaling parameter W against a fixed regex; the message echoes the simplified pattern the value must match (an optional minus, then either 0, a multi-digit number, 'L+n', or a plain positive number). A non-matching value throws ConfigurationException.

Source

Thrown at src/java/org/apache/cassandra/db/compaction/UnifiedCompactionStrategy.java:124

    {
        return Controller.validateOptions(AbstractCompactionStrategy.validateOptions(options));
    }

    public static int fanoutFromScalingParameter(int w)
    {
        return w < 0 ? 2 - w : 2 + w; // see formula in design doc
    }

    public static int thresholdFromScalingParameter(int w)
    {
        return w <= 0 ? 2 : 2 + w; // see formula in design doc
    }

    public static int parseScalingParameter(String value)
    {
        Matcher m = SCALING_PARAMETER_PATTERN.matcher(value);
        if (!m.matches())
            throw new ConfigurationException("Scaling parameter " + value + " must match " + SCALING_PARAMETER_PATTERN_SIMPLIFIED);

        if (m.group(1) != null)
            return 0;
        else if (m.group(2) != null)
            return 2 - atLeast2(Integer.parseInt(m.group(2)), value);
        else if (m.group(3) != null)
            return atLeast2(Integer.parseInt(m.group(3)), value) - 2;
        else
            return Integer.parseInt(m.group(4));
    }

    private static int atLeast2(int value, String str)
    {
        if (value < 2)
            throw new ConfigurationException("Fan factor cannot be lower than 2 in " + str);
        return value;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Provide a value matching the pattern, e.g. '-1', '0', '5', or 'L+4'
2. Check the intended form: optional '-' prefix; 0; multi-digit integer; 'L+n'; or small positive integer
3. Catch ConfigurationException when applying the table option
4. Consult UCS documentation for the meaning of O(W) vs L(n) scaling forms

Example fix

// before
'scaling_wainer': 'x2'
// after
'scaling_wainer': '2'

private static final Pattern SCALING = Pattern.compile("-?(0|\\d{2,}|L\\+\\d+|\\d)");
if (opts.containsKey("scaling_wainer") && !SCALING.matcher(opts.get("scaling_wainer")).matches())
    throw new IllegalArgumentException("scaling parameter must match the simplified UCS pattern");

static boolean isValidScalingParameter(String s) { return s != null && s.matches("-?(0|\\d{2,}|L\\+\\d+|\\d)"); }

try {
    session.execute(alterStmt);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Scaling parameter")) { /* correct the option and retry */ }
    throw e;
}

When it happens

Trigger: Configuring scaling_wainer / scaling_parameter option of UnifiedCompactionStrategy (e.g. 'min_sstable_size', 'scaling_wainer' style entries) with a value like 'abc', '3.5', 'x2', '+5', or an empty string.

Common situations: Typos in the compaction option; copying documentation examples that omit the accepted grammar; tools writing floats instead of integers or 'L+n' expressions.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Fan factor cannot be lower than 2 in %s
• Invalid configuration, %s should be positive: %d
• %s is not a parsable int (base10) for %s
• %s %s is out of range of Long.
• concurrent_compactors should be strictly greater than 0, but

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