{"record":{"id":"5ae13f65c1fc9656","repo":"apache/dubbo","slug":"ticksperwheel-must-be-greater-than-0","errorCode":null,"errorMessage":"ticksPerWheel must be greater than 0: {}","messagePattern":"ticksPerWheel must be greater than 0: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/timer/HashedWheelTimer.java","lineNumber":241,"sourceCode":"     * @throws NullPointerException     if either of {@code threadFactory} and {@code unit} is {@code null}\n     * @throws IllegalArgumentException if either of {@code tickDuration} and {@code ticksPerWheel} is &lt;= 0\n     */\n    public HashedWheelTimer(\n        ThreadFactory threadFactory,\n        long tickDuration, TimeUnit unit, int ticksPerWheel,\n        long maxPendingTimeouts) {\n\n        if (threadFactory == null) {\n            throw new NullPointerException(\"threadFactory\");\n        }\n        if (unit == null) {\n            throw new NullPointerException(\"unit\");\n        }\n        if (tickDuration <= 0) {\n            throw new IllegalArgumentException(\"tickDuration must be greater than 0: \" + tickDuration);\n        }\n        if (ticksPerWheel <= 0) {\n            throw new IllegalArgumentException(\"ticksPerWheel must be greater than 0: \" + ticksPerWheel);\n        }\n\n        // Normalize ticksPerWheel to power of two and initialize the wheel.\n        wheel = createWheel(ticksPerWheel);\n        mask = wheel.length - 1;\n\n        // Convert tickDuration to nanos.\n        this.tickDuration = unit.toNanos(tickDuration);\n\n        // Prevent overflow.\n        if (this.tickDuration >= Long.MAX_VALUE / wheel.length) {\n            throw new IllegalArgumentException(String.format(\n                \"tickDuration: %d (expected: 0 < tickDuration in nanos < %d\",\n                tickDuration, Long.MAX_VALUE / wheel.length));\n        }\n        workerThread = threadFactory.newThread(worker);\n\n        this.maxPendingTimeouts = maxPendingTimeouts;","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/timer/HashedWheelTimer.java#L223-L259","documentation":"IllegalArgumentException thrown by the HashedWheelTimer constructor when ticksPerWheel is <= 0. The wheel size (number of buckets) determines how timeouts are distributed across the hash wheel — it must be a positive integer. The constructor checks this at the top level before delegating to createWheel(). A non-positive wheel size makes hash-based scheduling impossible.","triggerScenarios":"Passing a ticksPerWheel of 0 or negative to the HashedWheelTimer constructor. Common when the value comes from unvalidated configuration or an arithmetic expression that underflows.","commonSituations":"Configuration property for wheel size set to 0 or left unset; computed wheel size that evaluates to non-positive due to a formula error; passing 0 intentionally to mean 'default' without realizing it's invalid.","solutions":["Set ticksPerWheel to a positive power of two (e.g., 512, the Dubbo/Netty default) — it is normalized internally but should be positive.","Validate the value before construction and default to 512 if invalid.","Use the convenience constructors that default ticksPerWheel to 512 (e.g., HashedWheelTimer(factory, tickDuration, unit))."],"exampleFix":"// before\nint wheelSize = config.getWheelSize(); // 0 if unset\nnew HashedWheelTimer(factory, 100, TimeUnit.MILLISECONDS, wheelSize);\n\n// after\nint wheelSize = config.getWheelSize();\nif (wheelSize <= 0) wheelSize = 512;\nnew HashedWheelTimer(factory, 100, TimeUnit.MILLISECONDS, wheelSize);","handlingStrategy":"validation","validationCode":"if (ticksPerWheel <= 0) {\n    throw new IllegalArgumentException(\"ticksPerWheel must be positive, got: \" + ticksPerWheel);\n}\nint safeWheel = ticksPerWheel > 0 ? ticksPerWheel : 512; // default\nnew HashedWheelTimer(factory, tickDuration, unit, safeWheel);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate ticksPerWheel is a positive integer before construction.","Default to 512 (the Dubbo/Netty standard) when configuration is absent or invalid.","Prefer powers of two for wheel size (normalized internally anyway)."],"tags":["timer","validation","constructor","configuration"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}