java-native-access/jna · error · IllegalStateException

Need an initialized array

Error message

Need an initialized array

What it means

Pointer.getValue throws IllegalStateException when the target type is an array but the current value is null. JNA reads array data into the existing Java array object; it cannot allocate a new one during a memory read, so an initialized array must be supplied.

Source

Thrown at src/com/sun/jna/Pointer.java:448

                result = currentValue;
            }
        } else if (NativeMapped.class.isAssignableFrom(type)) {
            NativeMapped nm = (NativeMapped)currentValue;
            if (nm != null) {
                Object value = getValue(offset, nm.nativeType(), null);
                result = nm.fromNative(value, new FromNativeContext(type));
                if (nm.equals(result)) {
                    result = nm;
                }
            } else {
                NativeMappedConverter tc = NativeMappedConverter.getInstance(type);
                Object value = getValue(offset, tc.nativeType(), null);
                result = tc.fromNative(value, new FromNativeContext(type));
            }
        } else if (type.isArray()) {
            result = currentValue;
            if (result == null) {
                throw new IllegalStateException("Need an initialized array");
            }
            readArray(offset, result, type.getComponentType());
        } else {
            throw new IllegalArgumentException("Reading \"" + type + "\" from memory is not supported");
        }
        return result;
    }

    /** Read memory starting at offset into the array with element type cls. */
    private void readArray(long offset, Object o, Class<?> cls) {
        int length = 0;
        length = Array.getLength(o);
        Object result = o;

        if (cls == byte.class) {
            read(offset, (byte[])result, 0, length);
        }
        else if (cls == short.class) {

View on GitHub (pinned to d036ad9781)

Solutions

1. Initialize array fields before reading: new byte[len] with the correct length
2. Call Structure.read() only after all array fields are allocated
3. Use Structure array-field constructors or allocate in the field initializer
4. If length is dynamic, use Pointer + read(offset, array, 0, len) manually instead of typed array fields

Example fix

// before
class S extends Structure {
    public byte[] data; // never initialized
}
// after
class S extends Structure {
    public byte[] data = new byte[64];
}

if (arr == null) {
    arr = new byte[expectedLength];
}

When it happens

Trigger: Reading a Structure field typed as an array (e.g. byte[] or int[]) that was left null; calling Pointer.getValue(offset, int[].class, null) directly.

Common situations: Structures where the array field was never assigned before reading from native memory; partially mapped structs where only some fields are initialized.

Related errors

• Nested Structure arrays must use a derived Structure type so
• Array fields must be initialized
• Function <name> declared Structure[] at parameter <index> bu
• Function <name> declared Structure[] at parameter <index> bu
• Structure array must have non-zero length

AI-assisted analysis of java-native-access/jna@d036ad9781 (2026-09-12). Data as JSON: /api/errors/e331062c7d16f729. Report an issue: GitHub.