{"record":{"id":"e2580ccf588d9fd2","repo":"java-native-access/jna","slug":"byte-boundary-must-be-a-power-of-two","errorCode":null,"errorMessage":"Byte boundary must be a power of two","messagePattern":"Byte boundary must be a power of two","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Memory.java","lineNumber":181,"sourceCode":"        if (byteBoundary <= 0) {\n            throw new IllegalArgumentException(\"Byte boundary must be positive: \" + byteBoundary);\n        }\n        for (int i=0;i < 32;i++) {\n            if (byteBoundary == (1<<i)) {\n                long mask = ~((long)byteBoundary - 1);\n\n                if ((peer & mask) != peer) {\n                    long newPeer = (peer + byteBoundary - 1) & mask;\n                    long newSize = peer + size - newPeer;\n                    if (newSize <= 0) {\n                        throw new IllegalArgumentException(\"Insufficient memory to align to the requested boundary\");\n                    }\n                    return (Memory)share(newPeer - peer, newSize);\n                }\n                return this;\n            }\n        }\n        throw new IllegalArgumentException(\"Byte boundary must be a power of two\");\n    }\n\n    /** Free the native memory and set peer to zero */\n    @Override\n    public void close() {\n        peer = 0;\n        if (cleanable != null) {\n            cleanable.clean();\n        }\n    }\n\n    @Deprecated\n    protected void dispose() {\n        close();\n    }\n\n    /** Zero the full extent of this memory region. */\n    public void clear() {","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Memory.java#L163-L199","documentation":"Memory.align() only supports byte boundaries that are powers of two (1, 2, 4, 8, 16...), because it computes the aligned address with a bitmask (~boundary-1). Any other value cannot produce a valid mask, so JNA falls through the loop and throws IllegalArgumentException.","triggerScenarios":"Calling memory.align(n) or aligned(n) where n is not a power of two, e.g. align(3), align(6), align(0), or a negative value — the while loop (boundary >= 2, halving) never matches and control reaches the throw.","commonSituations":"Passing a struct size or alignment guess like 3 or 6 instead of the next power of two; typos such as align(10); unit tests testInvalidAlignment exercising invalid boundaries.","solutions":["Pass a power-of-two boundary: use Integer.highestOneBit(n) or the next power of two ≥ n.","Use a standard alignment constant (1, 2, 4, 8, 16).","Guard the call: if (Integer.bitCount(boundary) != 1) pick a valid boundary before aligning."],"exampleFix":"// before\nMemory aligned = mem.align(6); // IllegalArgumentException\n// after\nint boundary = Integer.highestOneBit(6) * 2; // 8, next power of two\nMemory aligned = mem.align(boundary);","handlingStrategy":"validation","validationCode":"if (boundary <= 0 || Long.bitCount(boundary) != 1) {\n    throw new IllegalArgumentException(\"boundary must be a positive power of two: \" + boundary);\n}\nMemory aligned = memory.align(boundary);","typeGuard":"boolean isPowerOfTwo(long n) {\n    return n > 0 && (n & (n - 1)) == 0;\n}","tryCatchPattern":"try {\n    aligned = memory.align(boundary);\n} catch (IllegalArgumentException e) {\n    long next = Long.highestOneBit(boundary) * 2; // round up to next power of two\n    aligned = memory.align(next);\n}","preventionTips":["Only pass literal powers of two (1, 2, 4, 8, 16, 32).","Derive boundaries with Integer/Long.highestOneBit instead of hand-computed values.","Assert isPowerOfTwo(boundary) in debug builds before calling align."],"tags":["jna","native-memory","alignment","power-of-two"],"backgroundTag":"invalid-argument-value","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}