apache/cassandra · error · IllegalArgumentException

Invalid ratio definition:

Error message

Invalid ratio definition: 

What it means

OptionRatioDistribution.get(String) is a convenience factory: it builds a fresh OptionRatioDistribution, calls accept(spec) to parse a ratio distribution spec like 'uniform(1..100)/<ratio>', and throws 'Invalid ratio definition: <spec>' if the spec fails to parse. Ratio distributions weight distributions by a ratio value.

Solutions

1. Use a valid spec format: OptionRatioDistribution.get("uniform(1..100)/1")
2. Verify the distribution name and its parameters match OptionDistribution syntax
3. Print/inspect the spec string for hidden whitespace or quotes before parsing.

Example fix

// before
OptionRatioDistribution.get("unifrm(1..100)");
// after
OptionRatioDistribution.get("uniform(1..100)/1");

boolean validRatioSpec(String s){ return s.matches("(uniform|gaussian|fixed|seq|normal|weibull)\\([^)]*\\)/\\d+(\\.\\d+)?"); }

try { RatioDistributionFactory f = OptionRatioDistribution.get(spec); } catch (IllegalArgumentException e) { throw new IllegalArgumentException("Invalid ratio distribution spec '" + spec + "': expected <distribution(params)>/<ratio>", e); }

When it happens

Trigger: Calling OptionRatioDistribution.get() with a malformed spec, e.g. an unknown distribution name, bad bounds, missing ratio denominator, or an empty string.

Common situations: Hand-written stress profile weights with typos; using a distribution kind not supported for ratios; missing the '/' ratio part; wrong parameter counts inside parentheses.

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

• Invalid parameter list for fixed distribution:
• Invalid parameter list for sequence distribution:
• arguments for -F are json, yaml, table only.
• Cannot specify tokens without keyspace.
• Illegal distribution specification:

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

Appendix: source

Thrown at tools/stress/src/org/apache/cassandra/stress/settings/OptionRatioDistribution.java:80

        delegate = new OptionDistribution(prefix, null, description, required);
        this.defaultSpec = defaultSpec;
    }

    @Override
    public boolean accept(String param)
    {
        Matcher m = FULL.matcher(param);
        if (!m.matches() || !delegate.accept(m.group(1)))
            return false;
        divisor = OptionDistribution.parseLong(m.group(2));
        return true;
    }

    public static RatioDistributionFactory get(String spec)
    {
        OptionRatioDistribution opt = new OptionRatioDistribution("", "", "", true);
        if (!opt.accept(spec))
            throw new IllegalArgumentException("Invalid ratio definition: "+spec);
        return opt.get();
    }

    public RatioDistributionFactory get()
    {
        if (delegate.setByUser())
            return new DelegateFactory(delegate.get(), divisor);
        if (defaultSpec == null)
            return null;
        OptionRatioDistribution sub = new OptionRatioDistribution("", null, null, true);
        if (!sub.accept(defaultSpec))
            throw new IllegalStateException("Invalid default spec: " + defaultSpec);
        return sub.get();
    }

    @Override
    public boolean happy()
    {

View on GitHub (pinned to 88fd0f6a0e)