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

SettingsCommandUser aggregates op ratios across the loaded profiles; ops() expressions assign weights to named operations. After parsing profiles and ratios, the constructor requires that at least one operation has a non-zero ratio — this error means every supplied ops() weight was zero or no ops() entries resolved, so there would be no operations to run.

Source

Thrown at tools/stress/src/org/apache/cassandra/stress/settings/SettingsCommandUser.java:97

            	yamlURI = URI.create(curYamlPath);
            	String uriScheme = yamlURI.getScheme();
            	if (uriScheme == null || "file".equals(uriScheme)) {
                    throw new IllegalArgumentException("File '" + yamlURI.getPath() + "' doesn't exist!");
            	}
            }
            StressProfile profile = StressProfile.load(yamlURI);
            String specName = profile.specName;
            if (default_profile_name == null) {default_profile_name=specName;} //first file is default
            if (profiles.containsKey(specName))
            {
                throw new IllegalArgumentException("Must only specify a singe YAML file per table (including keyspace qualifier).");
            }
            profiles.put(specName, profile);
        }


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

    public boolean hasInsertOnly()
    {
        return ratios.size() == 1 && ratios.containsKey("insert");
    }

    public OpDistributionFactory getFactory(final StressSettings settings)
    {
        final SeedManager seeds = new SeedManager(settings);

        final Map<String, TokenRangeIterator> tokenRangeIterators = new LinkedHashMap<>();
        profiles.forEach((k,v)->tokenRangeIterators.put(k, (v.tokenRangeQueries.isEmpty()
                                                            ? null
                                                            : new TokenRangeIterator(settings,
                                                                                     v.maybeLoadTokenRanges(settings)))));

        return new SampledOpDistributionFactory<String>(ratios, clustering)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set at least one positive weight in ops(), e.g. ops(insert=3,read=1).
2. Ensure each ops() key matches an operation name defined in the profile YAML exactly.
3. Check your script/config isn't zeroing out all weights.
4. Run with 'cassandra-stress user profile=... ops(...)' including ops explicitly rather than relying on defaults.

Example fix

// before
cassandra-stress user profile=p.yaml ops(insert=0)
// after
cassandra-stress user profile=p.yaml ops(insert=1)

boolean anyPositive = opsWeights.values().stream().anyMatch(v -> v > 0);
if (!anyPositive) throw new IllegalArgumentException("at least one ops() weight must be > 0");

When it happens

Trigger: Running 'cassandra-stress user profile=p.yaml ops(insert=0,read=0)' or ops names that don't match any operation defined in the YAML (so no ratios register), making ratios.size() == 0.

Common situations: Script-generated weights that evaluate to zero; op names mismatching the YAML-defined operation names (case/typo); forgetting the ops() argument entirely; multiplying weights by a config value that resolves to 0.

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