{"record":{"id":"13de1dda1d61e31d","repo":"java-native-access/jna","slug":"argument-value-0x-value-exceeds-native-capacity-size-bytes","errorCode":null,"errorMessage":"Argument value 0x<value> exceeds native capacity (<size> bytes) mask=0x<mask>","messagePattern":"Argument value 0x<value> exceeds native capacity \\(<size> bytes\\) mask=0x<mask>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/IntegerType.java","lineNumber":110,"sourceCode":"                break;\n            case 4:\n                if (unsigned) {\n                    this.value = value & 0xFFFFFFFFL;\n                }\n                truncated = (int) value;\n                this.number = Integer.valueOf((int) value);\n                break;\n            case 8:\n                this.number = Long.valueOf(value);\n                break;\n            default:\n                throw new IllegalArgumentException(\"Unsupported size: \" + size);\n        }\n        if (size < 8) {\n            long mask = ~((1L << (size * 8)) - 1);\n            if ((value < 0 && truncated != value)\n                    || (value >= 0 && (mask & value) != 0)) {\n                throw new IllegalArgumentException(\"Argument value 0x\"\n                        + Long.toHexString(value) + \" exceeds native capacity (\"\n                        + size + \" bytes) mask=0x\" + Long.toHexString(mask));\n            }\n        }\n    }\n\n    @Override\n    public Object toNative() {\n        return number;\n    }\n\n    @Override\n    public Object fromNative(Object nativeValue, FromNativeContext context) {\n        // be forgiving of null values read from memory\n        long value = nativeValue == null\n            ? 0 : ((Number) nativeValue).longValue();\n        IntegerType number = Klass.newInstance(getClass());\n        number.setValue(value);","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/IntegerType.java#L92-L128","documentation":"IntegerType.setValue throws this IllegalArgumentException when a value does not fit in the declared native width: for unsigned types the value exceeds the mask of the size in bytes, or a negative value is not representable after truncation. It protects against silently truncating values when crossing the Java/native boundary.","triggerScenarios":"new ULONG(-1) or new UINT32(0xFFFFFFFFL + 1) style calls; passing a long larger than the type's capacity (e.g. 2^40 into a 4-byte type); fromNative receiving a value with bits set above size*8.","commonSituations":"Storing unsigned constants in signed Java longs (e.g. 0xFFFFFFFF for a 4-byte unsigned type is fine, but -1 is not); arithmetic overflow before constructing the type; mixing up signed/unsigned IntegerType subclasses.","solutions":["Mask the value before assignment: value & 0xFFFFFFFFL for a 4-byte unsigned type.","Use the signed variant (e.g. SWORD instead of UWORD) if negative values are legal.","Widen the type (e.g. use an 8-byte NativeLong/Long type) if values genuinely exceed capacity."],"exampleFix":"// before\nnew UINT(value); // value = 0x1_FFFF_FFFFL, > 4 bytes\n// after\nnew UINT(value & 0xFFFFFFFFL);","handlingStrategy":"validation","validationCode":"static long maskFor(int sizeBytes) { return sizeBytes >= 8 ? ~0L : (1L << (sizeBytes * 8)) - 1; }\nstatic long checkedUnsigned(long value, int sizeBytes) {\n  long m = maskFor(sizeBytes);\n  if ((value & ~m) != 0 && value >= 0) throw new IllegalArgumentException(\"0x\" + Long.toHexString(value) + \" > \" + sizeBytes + \" bytes\");\n  return value & m;\n}","typeGuard":null,"tryCatchPattern":"try {\n  new ULONG(rawValue);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"exceeds native capacity\")) {\n    throw new IllegalStateException(\"Value 0x\" + Long.toHexString(rawValue) + \" does not fit; mask before constructing\", e);\n  }\n  throw e;\n}","preventionTips":["Mask values (& 0xFF/0xFFFF/0xFFFFFFFFL) before constructing unsigned types.","Use signed IntegerType subclasses when negative values are expected.","Never do arithmetic that can overflow before constructing the type.","Model unsigned 64-bit values carefully; long is signed in Java."],"tags":["jna","integertype","overflow","unsigned"],"backgroundTag":"value-out-of-range","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}