java-native-access/jna · critical · Error

Native library not initialized

Error message

Native library not initialized

What it means

Structure's static initializer verifies that the native JNA library has been loaded and initialized by checking Native.POINTER_SIZE. If it is 0, the native library was never loaded (or failed to load), so any Structure use would be unsafe and the class fails to initialize with this Error. Because it is thrown in a static block, it surfaces as an ExceptionInInitializerError wrapping this Error.

Source

Thrown at src/com/sun/jna/Structure.java:2074

                || typePointer.equals(FFITypes.ffi_type_sint8)
                || typePointer.equals(FFITypes.ffi_type_uint16)
                || typePointer.equals(FFITypes.ffi_type_sint16)
                || typePointer.equals(FFITypes.ffi_type_uint32)
                || typePointer.equals(FFITypes.ffi_type_sint32)
                || typePointer.equals(FFITypes.ffi_type_uint64)
                || typePointer.equals(FFITypes.ffi_type_sint64)
                || typePointer.equals(FFITypes.ffi_type_pointer);
        }

        private static boolean isFloatType(FFIType type) {
            Pointer typePointer = type.getPointer();
            return typePointer.equals(FFITypes.ffi_type_float)
                || typePointer.equals(FFITypes.ffi_type_double);
        }

        static {
            if (Native.POINTER_SIZE == 0)
                throw new Error("Native library not initialized");
            if (FFITypes.ffi_type_void == null)
                throw new Error("FFI types not initialized");
            ffiTypeInfo.put(FFITypes.ffi_type_void, Structure.newInstance(FFIType.class, FFITypes.ffi_type_void));
            ffiTypeInfo.put(FFITypes.ffi_type_float, Structure.newInstance(FFIType.class, FFITypes.ffi_type_float));
            ffiTypeInfo.put(FFITypes.ffi_type_double, Structure.newInstance(FFIType.class, FFITypes.ffi_type_double));
            ffiTypeInfo.put(FFITypes.ffi_type_longdouble, Structure.newInstance(FFIType.class, FFITypes.ffi_type_longdouble));
            ffiTypeInfo.put(FFITypes.ffi_type_uint8, Structure.newInstance(FFIType.class, FFITypes.ffi_type_uint8));
            ffiTypeInfo.put(FFITypes.ffi_type_sint8, Structure.newInstance(FFIType.class, FFITypes.ffi_type_sint8));
            ffiTypeInfo.put(FFITypes.ffi_type_uint16, Structure.newInstance(FFIType.class, FFITypes.ffi_type_uint16));
            ffiTypeInfo.put(FFITypes.ffi_type_sint16, Structure.newInstance(FFIType.class, FFITypes.ffi_type_sint16));
            ffiTypeInfo.put(FFITypes.ffi_type_uint32, Structure.newInstance(FFIType.class, FFITypes.ffi_type_uint32));
            ffiTypeInfo.put(FFITypes.ffi_type_sint32, Structure.newInstance(FFIType.class, FFITypes.ffi_type_sint32));
            ffiTypeInfo.put(FFITypes.ffi_type_uint64, Structure.newInstance(FFIType.class, FFITypes.ffi_type_uint64));
            ffiTypeInfo.put(FFITypes.ffi_type_sint64, Structure.newInstance(FFIType.class, FFITypes.ffi_type_sint64));
            ffiTypeInfo.put(FFITypes.ffi_type_pointer, Structure.newInstance(FFIType.class, FFITypes.ffi_type_pointer));
            for(FFIType f: ffiTypeInfo.values()) {
                f.read();
            }

View on GitHub (pinned to d036ad9781)

Solutions

1. Ensure jna.jar is on the classpath intact (not a repacked jar missing the native libraries); use the official Maven artifact com.sun.jna:jna
2. Force native initialization before first Structure use by calling Native.load/Native.register or any Native API and confirm no UnsatisfiedLinkError occurred
3. Check System.getProperty("os.name")/"os.arch" is a supported platform and add the matching jna native classifier or let JNA extract jnidispatch to a writable temp dir (check -Djna.tmpdir)
4. If embedding in native-image or a restricted environment, configure JNA resource bundling/extract rules or load jnidispatch explicitly with NativeLibrary
5. Catch ExceptionInInitializerError at first touch and log Native.POINTER_SIZE and the cause of native load failure to diagnose

Example fix

// before
new MyStructure(); // throws ExceptionInInitializerError(NoClassDefFoundError afterwards)
// after
Native.load("c", CLibrary.class); // triggers native init first
MyStructure s = new MyStructure();

// call before using any Structure
boolean nativeReady() {
    try { return com.sun.jna.Native.POINTER_SIZE != 0; }
    catch (Throwable t) { return false; }
}

try {
    new MyStructure();
} catch (ExceptionInInitializerError e) {
    // inspect e.getCause(): "Native library not initialized" => jnidispatch not loaded
    throw new IllegalStateException("JNA natives unavailable", e.getCause());
}

When it happens

Trigger: Accessing any Structure subclass (or calling Structure static methods like newInstance/autoRead) when Native.register/initialize was never run, when Native.load of jnidispatch failed, or when the native library binary is missing/unsupported for the platform.

Common situations: Shipping an application without the jna native loader dependencies (e.g. jna unpacked jar without jna-platform/native resources), running on an unsupported OS/architecture so jnidispatch cannot be extracted, classloading Structure before Native in a stripped/graalvm-native-image build, or a custom Native class where POINTER_SIZE was never set by native init.

Related errors

• Failed to create WbemLocator object.
• Error looking up CallbackProxy.callback() method
• Error loading DLLCallback class
• Invalid library name "<libname>"
• <libname> does not implement an interface: <interfaceClassNa

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