apache/cassandra · error · IllegalArgumentException

Illegal distribution specification:

Error message

Illegal distribution specification: 

What it means

OptionDistribution.get parses a distribution spec string like gaussian(1..100) or ~uniform(...). The spec must match the FULL pattern (optional '~' inverse prefix, distribution name, parenthesized args); otherwise no legal parse exists and it throws IllegalArgumentException 'Illegal distribution specification: <spec>'.

Solutions

1. Use the form name(arg,arg,...), e.g. uniform(1..1000) or gaussian(50..100)
2. Prefix with ~ only for inverse distributions, e.g. ~uniform(1..100)
3. Run the stress command help to list supported distribution formats

Example fix

// before
-pop uniform
// after
-pop uniform(1..1000000)

Pattern FULL = Pattern.compile("(~?)(\w+)\((.*)\)");
if (!FULL.matcher(spec).matches()) throw new IllegalArgumentException("Illegal distribution spec: " + spec);

boolean isValidDistSpec(String s) { return s != null && s.matches("~?\w+\(.*\)"); }

try { DistributionFactory f = OptionDistribution.get(spec); } catch (IllegalArgumentException e) { log.error("Distribution '{}' must match name(args), e.g. uniform(1..1000)", spec); }

When it happens

Trigger: Supplying a distribution option (e.g. -pop, lookback=, revisit=, visit=) whose string does not match name(args) syntax — e.g. 'uniform', 'uniform(1..100)extra', 'gausian(1..10)' with a malformed shape, or empty args.

Common situations: Missing parentheses in distribution specs; stray characters from shell quoting; forgetting the argument list entirely; typo in the overall spec format.

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

• Illegal distribution type:
• Invalid lookback distribution; max value is
• Invalid node identifier supplied:
• Invalid parameter list for extreme (Weibull) distribution:
• Invalid parameter list for fixed distribution:

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

Appendix: source

Thrown at tools/stress/src/org/apache/cassandra/stress/settings/OptionDistribution.java:100

        this.defaultSpec = defaultSpec;
        this.description = description;
        this.required = required;
    }

    @Override
    public boolean accept(String param)
    {
        if (!toLowerCaseLocalized(param).startsWith(prefix))
            return false;
        spec = param.substring(prefix.length());
        return true;
    }

    public static DistributionFactory get(String spec)
    {
        Matcher m = FULL.matcher(spec);
        if (!m.matches())
            throw new IllegalArgumentException("Illegal distribution specification: " + spec);
        boolean inverse = m.group(1).equals("~");
        String name = m.group(2);
        Impl impl = LOOKUP.get(toLowerCaseLocalized(name));
        if (impl == null)
            throw new IllegalArgumentException("Illegal distribution type: " + name);
        List<String> params = new ArrayList<>();
        m = ARGS.matcher(m.group(3));
        while (m.find())
            params.add(m.group());
        DistributionFactory factory = impl.getFactory(params);
        return inverse ? new InverseFactory(factory) : factory;
    }

    public DistributionFactory get()
    {
        return spec != null ? get(spec) : defaultSpec != null ? get(defaultSpec) : null;
    }

View on GitHub (pinned to 88fd0f6a0e)