{"record":{"id":"e0ed670d361d8992","repo":"apache/dubbo","slug":"ticksperwheel-may-not-be-greater-than-2-30","errorCode":null,"errorMessage":"ticksPerWheel may not be greater than 2^30: {}","messagePattern":"ticksPerWheel may not be greater than 2\\^30: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/timer/HashedWheelTimer.java","lineNumber":286,"sourceCode":"    protected void finalize() throws Throwable {\n        try {\n            super.finalize();\n        } finally {\n            // This object is going to be GCed and it is assumed the ship has sailed to do a proper shutdown. If\n            // we have not yet shutdown then we want to make sure we decrement the active instance count.\n            if (WORKER_STATE_UPDATER.getAndSet(this, WORKER_STATE_SHUTDOWN) != WORKER_STATE_SHUTDOWN) {\n                INSTANCE_COUNTER.decrementAndGet();\n            }\n        }\n    }\n\n    private static HashedWheelBucket[] createWheel(int ticksPerWheel) {\n        if (ticksPerWheel <= 0) {\n            throw new IllegalArgumentException(\n                \"ticksPerWheel must be greater than 0: \" + ticksPerWheel);\n        }\n        if (ticksPerWheel > 1073741824) {\n            throw new IllegalArgumentException(\n                \"ticksPerWheel may not be greater than 2^30: \" + ticksPerWheel);\n        }\n\n        ticksPerWheel = normalizeTicksPerWheel(ticksPerWheel);\n        HashedWheelBucket[] wheel = new HashedWheelBucket[ticksPerWheel];\n        for (int i = 0; i < wheel.length; i++) {\n            wheel[i] = new HashedWheelBucket();\n        }\n        return wheel;\n    }\n\n    private static int normalizeTicksPerWheel(int ticksPerWheel) {\n        int normalizedTicksPerWheel = ticksPerWheel - 1;\n        normalizedTicksPerWheel |= normalizedTicksPerWheel >>> 1;\n        normalizedTicksPerWheel |= normalizedTicksPerWheel >>> 2;\n        normalizedTicksPerWheel |= normalizedTicksPerWheel >>> 4;\n        normalizedTicksPerWheel |= normalizedTicksPerWheel >>> 8;\n        normalizedTicksPerWheel |= normalizedTicksPerWheel >>> 16;","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/timer/HashedWheelTimer.java#L268-L304","documentation":"IllegalArgumentException thrown by createWheel() when ticksPerWheel exceeds 1073741824 (2^30). The wheel size is normalized to the next power of two, so values above 2^30 would normalize to 2^31, which overflows int range for array allocation (Integer.MAX_VALUE = 2^31 - 1). The cap at 2^30 ensures the normalized power-of-two fits in a Java int array. Allocating such a massive wheel is also impractical in terms of memory.","triggerScenarios":"Passing a ticksPerWheel value greater than 1,073,741,824 (2^30) to the HashedWheelTimer constructor. The constructor's check (line 241) only rejects <= 0, so values up to 2^30 reach createWheel() which enforces the upper bound.","commonSituations":"Configuration or computed value that produces an extremely large wheel size; misunderstanding of the parameter leading to an unreasonably large value; arithmetic overflow in the caller's computation that yields a huge positive number.","solutions":["Use a reasonable wheel size — 512 is the default and sufficient for most workloads. Larger wheels (e.g., 2048, 4096) only help with very high timeout throughput.","Validate the wheel size before construction and cap it to a sane maximum.","Review how the wheel size value is computed or configured to find the source of the inflated number."],"exampleFix":"// before\nint size = computeWheelSize(); // accidentally returns Integer.MAX_VALUE\nnew HashedWheelTimer(factory, 100, TimeUnit.MILLISECONDS, size);\n\n// after\nint size = computeWheelSize();\nif (size <= 0) size = 512;\nif (size > 4096) size = 4096; // cap to reasonable max\nnew HashedWheelTimer(factory, 100, TimeUnit.MILLISECONDS, size);","handlingStrategy":"validation","validationCode":"if (ticksPerWheel > 1073741824) {\n    throw new IllegalArgumentException(\"ticksPerWheel too large: \" + ticksPerWheel);\n}\nint safeWheel = ticksPerWheel;\nif (safeWheel > 4096) safeWheel = 4096; // cap to practical maximum\nnew HashedWheelTimer(factory, tickDuration, unit, safeWheel);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use a reasonable wheel size (512–4096) — larger wheels waste memory for negligible benefit.","Validate wheel size from configuration and cap it before construction.","Investigate any computed wheel size that exceeds practical bounds."],"tags":["timer","validation","memory","constructor"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}