{"record":{"id":"3a12a826b5ac8ff6","repo":"java-native-access/jna","slug":"error-loading-dllcallback-class","errorCode":null,"errorMessage":"Error loading DLLCallback class","messagePattern":"Error loading DLLCallback class","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/com/sun/jna/CallbackReference.java","lineNumber":83,"sourceCode":"            new ConcurrentHashMap<>();\n    private static final Method PROXY_CALLBACK_METHOD;\n\n    static {\n        try {\n            PROXY_CALLBACK_METHOD = CallbackProxy.class.getMethod(\"callback\", new Class[] { Object[].class });\n        } catch(Exception e) {\n            throw new Error(\"Error looking up CallbackProxy.callback() method\");\n        }\n    }\n\n    private static final Class<?> DLL_CALLBACK_CLASS;\n\n    static {\n        if (Platform.isWindows()) {\n            try {\n                DLL_CALLBACK_CLASS = Class.forName(\"com.sun.jna.win32.DLLCallback\");\n            } catch(ClassNotFoundException e) {\n                throw new Error(\"Error loading DLLCallback class\", e);\n            }\n        } else {\n            DLL_CALLBACK_CLASS = null;\n        }\n    }\n\n    private static final Map<Callback, CallbackThreadInitializer> initializers = new WeakHashMap<>();\n    /**\n     * @param cb The {@link Callback} instance\n     * @param initializer The {@link CallbackThreadInitializer} - if {@code null} then the\n     * associated initializer instance is removed\n     * @return The previous initializer instance (may be {@code null})\n     */\n    static CallbackThreadInitializer setCallbackThreadInitializer(Callback cb, CallbackThreadInitializer initializer) {\n        synchronized(initializers) {\n            if (initializer != null) {\n                return initializers.put(cb, initializer);\n            } else {","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/CallbackReference.java#L65-L101","documentation":"Fatal java.lang.Error thrown in a static initializer of CallbackReference when running on Windows and Class.forName(\"com.sun.jna.win32.DLLCallback\") fails with ClassNotFoundException. The DLLCallback interface is an internal JNA class that must be present in every Windows deployment, so failing to load it indicates a broken or partial JNA installation. Like error 310, it surfaces as ExceptionInInitializerError on first use of any JNA callback.","triggerScenarios":"Platform.isWindows() is true and the first Callback usage triggers the static block; Class.forName cannot find com.sun.jna.win32.DLLCallback — the jar is incomplete, the win32 package was stripped by shading/proguard/tree-shaking, or a non-Windows-only jna variant was packaged.","commonSituations":"Fat-jar packaging that accidentally excluded com/sun/jna/win32/*; Android/GraalVM native-image or JavaFXpackager resource filtering removing 'unused' classes; mixing jna-platform classes from a different version than jna.jar; classloader isolation (e.g. OSGi, app servers) hiding the package.","solutions":["Confirm the class exists: 'unzip -l jna.jar | grep DLLCallback'; if missing, replace the jar with a complete official jna.jar release.","Exclude only matching versions: ship jna.jar and jna-platform.jar from the same release, and remove duplicates from WEB-INF/lib or the container's shared lib.","If packaging with shading/native-image, add config to keep com.sun.jna.** (ProGuard keep rule, GraalVM reflection-config for com.sun.jna.win32.DLLCallback).","As a diagnostic, run a tiny program calling Class.forName(\"com.sun.jna.win32.DLLCallback\") with the same classpath to isolate classloader problems."],"exampleFix":"// before (Windows startup)\njava.lang.ExceptionInInitializerError\n  Caused by: java.lang.Error: Error loading DLLCallback class\n  Caused by: java.lang.ClassNotFoundException: com.sun.jna.win32.DLLCallback\n// after (maven: single aligned version)\n<dependency><groupId>net.java.dev.jna</groupId><artifactId>jna</artifactId><version>5.14.0</version></dependency>\n<dependency><groupId>net.java.dev.jna</groupId><artifactId>jna-platform</artifactId><version>5.14.0</version></dependency>","handlingStrategy":"validation","validationCode":"// early check on Windows hosts\nif (Platform.isWindows()) {\n    try {\n        Class.forName(\"com.sun.jna.win32.DLLCallback\");\n    } catch (ClassNotFoundException e) {\n        throw new IllegalStateException(\"jna.jar missing win32 package\", e);\n    }\n}","typeGuard":null,"tryCatchPattern":"try { initJnaCallbacks(); } catch (ExceptionInInitializerError e) { throw new IllegalStateException(\"Incomplete JNA classpath (DLLCallback missing): \" + e.getCause(), e); }","preventionTips":["Keep jna.jar and jna-platform.jar versions aligned.","Check packaged artifacts (fat jar/native image) include com/sun/jna/win32/*.","Add a startup self-check loading DLLCallback on Windows.","Configure GraalVM native-image reflection entries for com.sun.jna.**."],"tags":["jna","classpath","class-not-found","windows","static-initializer"],"backgroundTag":"class-not-found","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}