apache/shenyu · error · IllegalArgumentException

probability should be between 0.01 and 1: was

Error message

probability should be between 0.01 and 1: was ${probability}

What it means

CountSampler.create parses a sampling probability string used for trace/log sampling. Values below 0.01 or above 1 cannot produce a meaningful sampling ratio (0 means never sample; the API deliberately floors at 1%), so it throws IllegalArgumentException naming the offending value.

Solutions

1. Set the probability within [0.01, 1], e.g. 0.1 for 10% sampling.
2. If you wanted no sampling, disable the logging plugin or the sampler entirely instead of passing 0.
3. Convert percentages: 50% -> 0.5.
4. Special-case strings "1", "1.0", "1.0.0" are accepted as always-sample; use one of those for full sampling.

Example fix

// before
CountSampler.create("0");
// after
CountSampler.create("0.01"); // minimum accepted rate

boolean validSamplingProbability(String p) {
    float v = NumberUtils.toFloat(p, 1);
    return !("0".equals(p)) && v >= 0.01f && v <= 1f;
}

try {
    sampler = CountSampler.create(probability);
} catch (IllegalArgumentException e) {
    sampler = CountSampler.create("0.01"); // safe minimum rate
    log.warn("Invalid sampling probability '{}', falling back to 0.01", probability);
}

When it happens

Trigger: Calling CountSampler.create with a numeric string that parses via NumberUtils.toFloat to a value < 0.01 or > 1 (e.g. "0", "0.001", "2.0"). Non-numeric strings fall back to 1 (always sample) and do NOT trigger this.

Common situations: Setting a sampling rate of 0 expecting 'never sample' (0 is rejected; use a rate at or above 0.01 or disable sampling another way); copy-pasting a percentage (50 for 50%); misconfigured plugin logging sampler config in the admin dashboard.

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

• Acquire Timeout value must be positive
• client register param must config the appName or contextPath
• Host is empty in Redis node URL: " + url
• Max Connections value must be strictly positive
• OpenAPI methodType cannot be null or empty

AI-assisted analysis of apache/shenyu@567142e072 (2026-09-12). Data as JSON: /api/errors/f1f2ff332509994e. Report an issue: GitHub.

Appendix: source

Thrown at shenyu-plugin/shenyu-plugin-logging/shenyu-plugin-logging-common/src/main/java/org/apache/shenyu/plugin/logging/common/sampler/CountSampler.java:112

    /**
     * create a sampler instance.
     *
     * @param probability probability
     * @return sampler instance
     */
    public static Sampler create(final String probability) {
        if (StringUtils.isBlank(probability)) {
            return ALWAYS_SAMPLE;
        }
        if ("0".equals(probability)) {
            return NEVER_SAMPLE;
        }
        if ("1".equals(probability) || "1.0".equals(probability) || "1.0.0".equals(probability)) {
            return ALWAYS_SAMPLE;
        }
        float parseProbability = NumberUtils.toFloat(probability, 1);
        if (parseProbability < 0.01f || parseProbability > 1) {
            throw new IllegalArgumentException(
                    "probability should be between 0.01 and 1: was " + probability);
        }
        return new CountSampler(parseProbability);
    }

}

View on GitHub (pinned to 567142e072)