{"record":{"id":"fde44705db9185a1","repo":"netty/netty","slug":"directmemorycachealignment-expected-power-of","errorCode":null,"errorMessage":"directMemoryCacheAlignment: {} (expected: power of two)","messagePattern":"directMemoryCacheAlignment: (.+?) \\(expected: power of two\\)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"buffer/src/main/java/io/netty/buffer/PooledByteBufAllocator.java","lineNumber":300,"sourceCode":"                        \"Either Unsafe or ByteBuffer.alignSlice() must be available.\");\n            }\n\n            // Ensure page size is a whole multiple of the alignment, or bump it to the next whole multiple.\n            pageSize = (int) PlatformDependent.align(pageSize, directMemoryCacheAlignment);\n        }\n\n        chunkSize = validateAndCalculateChunkSize(pageSize, maxOrder);\n\n        checkPositiveOrZero(nHeapArena, \"nHeapArena\");\n        checkPositiveOrZero(nDirectArena, \"nDirectArena\");\n\n        checkPositiveOrZero(directMemoryCacheAlignment, \"directMemoryCacheAlignment\");\n        if (directMemoryCacheAlignment > 0 && !isDirectMemoryCacheAlignmentSupported()) {\n            throw new IllegalArgumentException(\"directMemoryCacheAlignment is not supported\");\n        }\n\n        if ((directMemoryCacheAlignment & -directMemoryCacheAlignment) != directMemoryCacheAlignment) {\n            throw new IllegalArgumentException(\"directMemoryCacheAlignment: \"\n                    + directMemoryCacheAlignment + \" (expected: power of two)\");\n        }\n\n        int pageShifts = validateAndCalculatePageShifts(pageSize, directMemoryCacheAlignment);\n\n        if (nHeapArena > 0) {\n            heapArenas = newArenaArray(nHeapArena);\n            List<PoolArenaMetric> metrics = new ArrayList<PoolArenaMetric>(heapArenas.length);\n            final SizeClasses sizeClasses = new SizeClasses(pageSize, pageShifts, chunkSize, 0);\n            for (int i = 0; i < heapArenas.length; i ++) {\n                PoolArena.HeapArena arena = new PoolArena.HeapArena(this, sizeClasses);\n                heapArenas[i] = arena;\n                metrics.add(arena);\n            }\n            heapArenaMetrics = Collections.unmodifiableList(metrics);\n        } else {\n            heapArenas = null;\n            heapArenaMetrics = Collections.emptyList();","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/netty/netty/blob/70040aacae241e9ba371e758f5b86e470bd77ad1/buffer/src/main/java/io/netty/buffer/PooledByteBufAllocator.java#L282-L318","documentation":"Thrown by the PooledByteBufAllocator constructor when directMemoryCacheAlignment is not a power of two. The test (alignment & -alignment) != alignment isolates the lowest set bit; equality holds only for powers of two. It is an IllegalArgumentException: the allocator aligns buffer addresses via bit-masking, which requires a single-bit alignment value.","triggerScenarios":"Passing a directMemoryCacheAlignment such as 3, 6, 12, 24, 48 — non-powers of two that a developer picked from a CPU cache-line intuition without converting to the nearest power of two.","commonSituations":"Using the literal L1/L2 cache line size (e.g. 48 or 96 bytes on some CPUs) instead of rounding to 32/64/128; mirroring a C struct alignment value that is not a power of two.","solutions":["Use a power of two: 1, 2, 4, 8, 16, 32, 64, 128 (64 is typical for cache lines).","Round up: alignment = Integer.highestOneBit(requested - 1) << 1; then guard against 0.","If alignment is unnecessary, set it to 0."],"exampleFix":"// before\nnew PooledByteBufAllocator(true, nHeap, nDirect, pageSize, maxOrder, small, normal, true, 48);\n\n// after\nint alignment = Integer.highestOneBit(requestedLine - 1) << 1; // 48 -> 64\nnew PooledByteBufAllocator(true, nHeap, nDirect, pageSize, maxOrder, small, normal, true, alignment);","handlingStrategy":"validation","validationCode":"static int pow2Alignment(int requested) {\n    if (requested <= 0) return 0;\n    int p = Integer.highestOneBit(requested - 1) << 1;\n    return p < 1 ? 1 : p;\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Use powers of two for alignment (64 is typical for cache lines).","Round up non-powers-of-two with highestOneBit before passing.","Set alignment to 0 when alignment is not required."],"tags":["netty","buffer","pooled-allocator","alignment","illegal-argument"],"backgroundTag":null,"analyzedSha":"70040aacae241e9ba371e758f5b86e470bd77ad1","analyzedAt":"2026-08-14T01:29:15.551Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}