apache/cassandra · error · ConfigurationException

Invalid value for PERCENTILE option ' ': must be between…

Error message

Invalid value %s for PERCENTILE option '%s': must be between (0.0 and 100.0)

What it means

Thrown by PercentileSpeculativeRetryPolicy.fromString when the parsed percentile is <= 0.0 or >= 100.0. A percentile of exactly 0 or 100 is rejected because speculative retries at those bounds are meaningless (0 = never, 100 = always) and the policy requires an open-interval value.

Solutions

Pick a value strictly between 0 and 100, e.g. '99p' or '50p'
Use speculative_retry = 'NONE' to disable speculative retries entirely
Use 'ALWAYS' if you truly want a retry on every read

Example fix

// before
ALTER TABLE ks.tbl WITH speculative_retry = '100p';
// after
ALTER TABLE ks.tbl WITH speculative_retry = '99p';

Defensive patterns

Strategy: validation

Validate before calling

function checkPercentileRange(v) {
  const m = /^([0-9]*\.?[0-9]+)(p|PERCENTILE)$/i.exec(v.trim());
  if (!m) return false;
  const n = parseFloat(m[1]);
  if (n <= 0.0 || n >= 100.0) throw new RangeError(`percentile ${n} must be between (0.0 and 100.0)`);
  return true;
}

Prevention

Reject 0p/100p in config generation; map them to NONE/ALWAYS explicitly
Clamp generated percentiles to [0.1, 99.9]
Document in runbooks that bounds are exclusive

When it happens

Trigger: speculative_retry set to '0p', '100p', '0.0PERCENTILE', '100.0PERCENTILE', or a negative value like '-5p' in CREATE/ALTER TABLE.

Common situations: Users trying to disable retries with '0p' (use NONE instead); trying '100p' to 'always retry'; templated configs where 100 means percent-complete rather than percentile.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/reads/PercentileSpeculativeRetryPolicy.java:112

        if (!matcher.matches())
            throw new IllegalArgumentException();

        String val = matcher.group("val");

        double percentile;
        try
        {
            percentile = Double.parseDouble(val);
        }
        catch (IllegalArgumentException e)
        {
            throw new ConfigurationException(String.format("Invalid value %s for option '%s'", str, TableParams.Option.SPECULATIVE_RETRY));
        }

        if (percentile <= 0.0 || percentile >= 100.0)
        {
            throw new ConfigurationException(String.format("Invalid value %s for PERCENTILE option '%s': must be between (0.0 and 100.0)",
                                                           str, TableParams.Option.SPECULATIVE_RETRY));
        }

        return new PercentileSpeculativeRetryPolicy(percentile);
    }

    static boolean stringMatches(String str)
    {
        return PATTERN.matcher(str).matches();
    }
}

View on GitHub (pinned to 88fd0f6a0e)