{"record":{"id":"643bda251ce73529","repo":"java-native-access/jna","slug":"byte-boundary-must-be-positive-byteboundary","errorCode":null,"errorMessage":"Byte boundary must be positive: <byteBoundary>","messagePattern":"Byte boundary must be positive: <byteBoundary>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Memory.java","lineNumber":164,"sourceCode":"     * the allocated bounds.\n     */\n    @Override\n    public Pointer share(long offset, long sz) {\n        boundsCheck(offset, sz);\n        return new SharedMemory(offset, sz);\n    }\n\n    /** Provide a view onto this structure with the given alignment.\n     * @param byteBoundary Align memory to this number of bytes; should be a\n     * 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    }","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Memory.java#L146-L182","documentation":"Memory.align throws this IllegalArgumentException when the requested byteBoundary is not positive. The doc requires a positive power of two; non-positive values are rejected immediately, and non-powers-of-two fall through to the UnsupportedOperationException below the shown region.","triggerScenarios":"mem.align(0) or mem.align(-4); boundary computed from an expression that yielded 0; passing a value like 6 (rejected by the power-of-two loop, not this message).","commonSituations":"Aligning buffers to struct member alignment where the alignment constant was uninitialized; computing alignment from sizeof results on empty structs; confusing byte boundary with byte offset.","solutions":["Pass a positive power of two: 1, 2, 4, 8, 16, ...","Compute alignment from the actual type: use Native.getNativeSize or Structure field alignment instead of hardcoded 0.","Guard: if (boundary <= 0 || (boundary & (boundary-1)) != 0) fix before calling align()."],"exampleFix":"// before\nint boundary = config.get(\"align\", 0);\nmem.align(boundary);\n// after\nint boundary = Math.max(1, config.get(\"align\", 8));\nmem.align(Integer.highestOneBit(boundary));","handlingStrategy":"validation","validationCode":"static boolean isPowerOfTwo(int n) { return n > 0 && (n & (n - 1)) == 0; }\nstatic Memory safeAlign(Memory m, int boundary) {\n  if (!isPowerOfTwo(boundary)) throw new IllegalArgumentException(\"Alignment must be a positive power of two: \" + boundary);\n  return m.align(boundary);\n}","typeGuard":null,"tryCatchPattern":"try {\n  Memory aligned = mem.align(boundary);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().startsWith(\"Byte boundary must be positive\")) {\n    throw new IllegalStateException(\"boundary=\" + boundary + \"; use a positive power of two\", e);\n  }\n  throw e;\n}","preventionTips":["Use constants (1,2,4,8,16) for alignment, never computed-zero values.","Validate alignment with n>0 && (n&(n-1))==0.","Derive alignment from Native.getNativeSize / Structure alignment APIs.","Watch the follow-on UnsupportedOperationException for non-power-of-two values."],"tags":["jna","memory","alignment","invalid-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-14T11:17:12.474Z"}