{"record":{"id":"500393386d5253e0","repo":"java-native-access/jna","slug":"could-not-access-instance-of-cls-cause","errorCode":null,"errorMessage":"Could not access instance of <cls> (<cause>)","messagePattern":"Could not access instance of <cls> \\(<cause>\\)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Native.java","lineNumber":767,"sourceCode":"     * Expects that lock on libraries is already held\n     */\n    private static void loadLibraryInstance(Class<?> cls) {\n        if (cls != null && !libraries.containsKey(cls)) {\n            try {\n                Field[] fields = cls.getFields();\n                for (int i=0;i < fields.length;i++) {\n                    Field field = fields[i];\n                    if (field.getType() == cls\n                        && Modifier.isStatic(field.getModifiers())) {\n                        // Ensure the field gets initialized by reading it\n                        field.setAccessible(true); // interface might be private\n                        libraries.put(cls, new WeakReference<>(field.get(null)));\n                        break;\n                    }\n                }\n            }\n            catch (Exception e) {\n                throw new IllegalArgumentException(\"Could not access instance of \"\n                                                   + cls + \" (\" + e + \")\");\n            }\n        }\n    }\n\n    /**\n     * Find the library interface corresponding to the given class.  Checks\n     * all ancestor classes and interfaces for a declaring class which\n     * implements {@link Library}.\n     * @param cls The given class\n     * @return The enclosing class\n     */\n    static Class<?> findEnclosingLibraryClass(Class<?> cls) {\n        if (cls == null) {\n            return null;\n        }\n        // Check for direct-mapped libraries, which won't necessarily\n        // implement com.sun.jna.Library.","sourceCodeStart":749,"sourceCodeEnd":785,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Native.java#L749-L785","documentation":"Native's library-registration path reads the mapped library instance from a static field of the interface class via reflection (field.get(null)). If any reflective access fails (security manager, inaccessible field, IllegalAccessException, etc.), JNA wraps the exception in an IllegalArgumentException: 'Could not access instance of <cls> (<cause>)'.","triggerScenarios":"Calling Native.loadLibrary(Native.getLibraryClass(...)-style registration) / Native.synchronizedLibrary-style helpers where the static INSTANCE/WCE_INSTANCE-style field cannot be reflectively read — e.g. a non-static field, null value handled elsewhere, or a SecurityManager denying reflection.","commonSituations":"Running under a SecurityManager or restricted environment (app server, webstart) blocking reflective access; the interface was modified so the expected static field no longer exists or is not accessible; custom classloaders returning odd classes.","solutions":["Ensure the mapping interface has a public static final field holding the loaded library instance (convention: INSTANCE).","Remove the SecurityManager or add reflective-access permissions (ReflectPermission) for JNA.","Verify the class passed to the registration API actually is the library interface with a static instance.","Catch the IllegalArgumentException and inspect getCause() to see the underlying reflection failure."],"exampleFix":"// before\npublic interface FooLib { // no public static instance accessible\n    FooLib LIB = Native.load(\"foo\", FooLib.class); // package-private? non-standard name\n}\n// after\npublic interface FooLib extends Library {\n    FooLib INSTANCE = Native.load(\"foo\", FooLib.class); // public static field JNA can read\n}","handlingStrategy":"try-catch","validationCode":"Field f = mappingClass.getDeclaredField(\"INSTANCE\");\nif (!Modifier.isStatic(f.getModifiers()) || !Modifier.isPublic(f.getModifiers())) {\n    throw new IllegalStateException(\"library INSTANCE field must be public static\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    registerLibrary(mappingClass);\n} catch (IllegalArgumentException e) {\n    throw new IllegalStateException(\"Reflective access to \" + mappingClass\n        + \" failed: \" + e.getMessage(), e.getCause());\n}","preventionTips":["Follow the JNA convention: public static final <I> INSTANCE = Native.load(...) inside the interface.","Avoid SecurityManager-restricted environments, or grant ReflectPermission to JNA code.","Check e.getCause() to distinguish IllegalAccessException from other reflection failures."],"tags":["jna","reflection","illegal-access","library-registration"],"backgroundTag":"permission-denied","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"}