apache/cassandra · error · IllegalArgumentException

Must specify at least one command with a non-zero ratio

Error message

Must specify at least one command with a non-zero ratio

What it means

SettingsCommandPreDefinedMixed implements the 'mixed' predefined command, where each sub-command (read/write/insert/etc.) is assigned a probability ratio via the 'profile'/'ratio' style options. The constructor validates that the resulting ratio map is non-empty; this error means every command's ratio was zero or unset, leaving no operations to distribute.

Source

Thrown at tools/stress/src/org/apache/cassandra/stress/settings/SettingsCommandPreDefinedMixed.java:56

// Settings unique to the mixed command type
public class SettingsCommandPreDefinedMixed extends SettingsCommandPreDefined
{

    // Ratios for selecting commands - index for each Command, NaN indicates the command is not requested
    private final Map<Command, Double> ratios;
    private final DistributionFactory clustering;
    private final Options options;

    public SettingsCommandPreDefinedMixed(Options options)
    {
        super(Command.MIXED, options);

        clustering = options.clustering.get();
        ratios = options.probabilities.ratios();
        this.options = options;
        if (ratios.size() == 0)
            throw new IllegalArgumentException("Must specify at least one command with a non-zero ratio");
    }

    public OpDistributionFactory getFactory(final StressSettings settings)
    {
        final SeedManager seeds = new SeedManager(settings);
        return new SampledOpDistributionFactory<Command>(ratios, clustering)
        {
            protected List<? extends Operation> get(Timer timer, Command key, boolean isWarmup)
            {
                return Collections.singletonList(PredefinedOperation.operation(key, timer, SettingsCommandPreDefinedMixed.this.newGenerator(settings), seeds, settings, add));
            }
        };
    }

    // Option Declarations

    static class Options extends SettingsCommandPreDefined.Options
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Give at least one command a positive ratio, e.g. 'mixed ratio@read=3,ratio@write=1'.
2. Check for typos in ratio keys — they must match known command names (read, write, insert, counter_read, counter_write).
3. Ensure ratio values are positive numbers, not 0.
4. Print/echo the constructed option string in your script to verify ratios survive parameterization.

Example fix

// before
cassandra-stress mixed ratio@read=0,ratio@write=0
// after
cassandra-stress mixed ratio@read=1,ratio@write=1

boolean anyPositive = ratios != null && ratios.values().stream().anyMatch(v -> v > 0);
if (!anyPositive) throw new IllegalArgumentException("at least one command ratio must be > 0");

When it happens

Trigger: Running 'cassandra-stress mixed' where all supplied command ratios resolve to zero or none are supplied at all, causing options.probabilities.ratios() to return an empty map.

Common situations: Supplying only zero ratios like 'mixed ratio@media=0'; misspelling the ratio option so it's ignored; a script generating ratios that evaluates to all zeros; forgetting the ratio syntax entirely.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• You need to state at least one --target host to replay the q
• Invalid default spec:
• Must specify at least one command with a non-zero ratio
• Invalid data rate: value must be non-negative
• Invalid data storage: %s Accepted units:%s

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