{"record":{"id":"9cd747b602a81175","repo":"java-native-access/jna","slug":"insufficient-memory-to-align-to-the-requested-boundary","errorCode":null,"errorMessage":"Insufficient memory to align to the requested boundary","messagePattern":"Insufficient memory to align to the requested boundary","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Memory.java","lineNumber":174,"sourceCode":"     * power of two.\n     * @throws IndexOutOfBoundsException if the requested alignment can\n     * not be met.\n     * @throws IllegalArgumentException if the requested alignment is not\n     * a positive power of two.\n     */\n    public Memory align(int byteBoundary) {\n        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","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Memory.java#L156-L192","documentation":"Memory.align() adjusts this native memory block's start address up to the given byte boundary. When rounding the address up, the remaining usable space (newSize = peer + size - newPeer) can become zero or negative, meaning the aligned view would have no bytes left. JNA throws IllegalArgumentException in that case rather than returning an empty/shrunk Memory.","triggerScenarios":"Calling memory.align(byteBoundary) (directly or via memory.aligned()) where the current peer address is not already on the boundary and the number of bytes remaining after rounding up the address is <= 0 — i.e. the block is too small (or the offset too deep) to survive alignment.","commonSituations":"Aligning a small Memory block or a shared/sliced region (e.g. obtained from Memory.share) to a large boundary such as 8 or 16 bytes; writing tests like testNegativeAlignment/testInvalidAlignment that align blocks with little or no slack.","solutions":["Allocate a larger Memory block than needed so there is slack for boundary rounding (e.g. size + boundary).","Use a smaller byteBoundary that the block can accommodate.","Align once at allocation time (new Memory(size).align(boundary) on a suitably sized buffer) instead of aligning small shared slices.","Check math before calling: if ((peer + size) rounded down to boundary) <= peer, the align cannot succeed."],"exampleFix":"// before\nMemory m = new Memory(4);\nMemory aligned = m.align(16); // throws: nothing left after rounding up\n// after\nMemory m = new Memory(4 + 16);\nMemory aligned = m.align(16); // slack guarantees space survives alignment","handlingStrategy":"validation","validationCode":"long mask = ~(boundary - 1);\nlong newPeer = (peer + boundary - 1) & mask;\nlong newSize = peer + size - newPeer;\nif (newSize <= 0) {\n    throw new IllegalArgumentException(\"block too small for boundary \" + boundary);\n}\nMemory aligned = memory.align(boundary);","typeGuard":"boolean canAlign(Memory m, long boundary) {\n    return Long.bitCount(boundary) == 1 && m.size() >= boundary;\n}","tryCatchPattern":"try {\n    aligned = memory.align(boundary);\n} catch (IllegalArgumentException e) {\n    aligned = new Memory(size + boundary).align(boundary); // reallocate with slack\n}","preventionTips":["Always allocate size + boundary bytes if you plan to align afterwards.","Align at allocation time rather than on shared/sliced sub-regions.","Add unit tests covering small blocks and each boundary value you use."],"tags":["jna","native-memory","alignment","illegal-argument"],"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"}