{"record":{"id":"41d1d6d768c73429","repo":"apache/pulsar","slug":"jitterpercent-must-be-in-0-100-41d1d6","errorCode":null,"errorMessage":"jitterPercent must be in [0, 100]","messagePattern":"jitterPercent must be in \\[0, 100\\]","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-common/src/main/java/org/apache/pulsar/common/util/Backoff.java","lineNumber":228,"sourceCode":"         */\n        public Builder mandatoryStop(Duration mandatoryStop) {\n            this.mandatoryStop = mandatoryStop;\n            return this;\n        }\n\n        /**\n         * Sets the jitter percentage applied to each returned delay. The actual jitter is symmetric:\n         * the returned value is multiplied by a uniform random factor in\n         * {@code [1 - jitterPercent/200, 1 + jitterPercent/200)}. Defaults to 10. Set to 0 to disable\n         * jitter.\n         *\n         * @param jitterPercent the jitter percentage, must be in {@code [0, 100]}\n         * @return this builder\n         * @throws IllegalArgumentException if {@code jitterPercent} is outside {@code [0, 100]}\n         */\n        public Builder jitterPercent(double jitterPercent) {\n            if (jitterPercent < 0 || jitterPercent > 100) {\n                throw new IllegalArgumentException(\"jitterPercent must be in [0, 100]\");\n            }\n            this.jitterPercent = jitterPercent;\n            return this;\n        }\n\n        Builder clock(Clock clock) {\n            this.clock = clock;\n            return this;\n        }\n\n        /**\n         * Builds a new {@link Backoff} instance with the configured parameters.\n         *\n         * @return a new Backoff\n         */\n        public Backoff build() {\n            return new Backoff(initialDelay, maxBackoff, mandatoryStop, jitterPercent, clock);\n        }","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-common/src/main/java/org/apache/pulsar/common/util/Backoff.java#L210-L246","documentation":"Thrown by Backoff.Builder.jitterPercent when the supplied jitter percentage is outside the allowed [0, 100] range. Jitter is applied as a percentage of the computed backoff delay, so negative or >100 values are invalid and rejected eagerly at build time to fail fast rather than produce nonsensical retry delays.","triggerScenarios":"Calling Backoff.Builder().jitterPercent(x) with x < 0 or x > 100 — e.g. passing a ratio like 1.5 meaning 150% or intending a fraction (0.5) but exceeding 1.0 semantics differently.","commonSituations":"Confusing fraction (0.2 = 20%) with percent (20); reading jitter from config files with mis-scaled values; arithmetic producing NaN-adjacent or negative values from earlier computations; copy-pasting jitter settings between libraries with different units (ms vs %).","solutions":["Clamp or validate the configured value to [0, 100] before passing it to jitterPercent","Convert fractions to percent (multiply by 100) if your config stores ratios","Fix the configuration source providing the jitter value","Choose a sensible default (e.g. 20) when the input is missing or malformed"],"exampleFix":"// before\nnew Backoff.Builder().jitterPercent(cfg.getJitter()) // cfg.getJitter() = 0.2 (fraction)\n// after\nnew Backoff.Builder().jitterPercent(Math.min(100, Math.max(0, cfg.getJitter() * 100)))","handlingStrategy":"validation","validationCode":"double jp = cfg.getJitterPercent();\nif (jp < 0 || jp > 100 || !Double.isFinite(jp)) throw new IllegalArgumentException(\"jitterPercent out of [0,100]: \" + jp);","typeGuard":"static boolean isValidJitterPercent(double v) {\n    return Double.isFinite(v) && v >= 0 && v <= 100;\n}","tryCatchPattern":"try {\n    builder.jitterPercent(jp);\n} catch (IllegalArgumentException e) {\n    builder.jitterPercent(20); // sane default\n}","preventionTips":["Store jitter as percent (0-100), not fraction, and convert consistently","Clamp config-sourced values before building Backoff","Document unit conventions next to the config key","Sanity-check computed values for negative/overflow before passing"],"tags":["retry","backoff","validation","configuration"],"backgroundTag":"invalid-argument-range","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}