java-native-access/jna · critical · Error

Error loading DLLCallback class

Error message

Error loading DLLCallback class

What it means

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.

Source

Thrown at src/com/sun/jna/CallbackReference.java:83

            new ConcurrentHashMap<>();
    private static final Method PROXY_CALLBACK_METHOD;

    static {
        try {
            PROXY_CALLBACK_METHOD = CallbackProxy.class.getMethod("callback", new Class[] { Object[].class });
        } catch(Exception e) {
            throw new Error("Error looking up CallbackProxy.callback() method");
        }
    }

    private static final Class<?> DLL_CALLBACK_CLASS;

    static {
        if (Platform.isWindows()) {
            try {
                DLL_CALLBACK_CLASS = Class.forName("com.sun.jna.win32.DLLCallback");
            } catch(ClassNotFoundException e) {
                throw new Error("Error loading DLLCallback class", e);
            }
        } else {
            DLL_CALLBACK_CLASS = null;
        }
    }

    private static final Map<Callback, CallbackThreadInitializer> initializers = new WeakHashMap<>();
    /**
     * @param cb The {@link Callback} instance
     * @param initializer The {@link CallbackThreadInitializer} - if {@code null} then the
     * associated initializer instance is removed
     * @return The previous initializer instance (may be {@code null})
     */
    static CallbackThreadInitializer setCallbackThreadInitializer(Callback cb, CallbackThreadInitializer initializer) {
        synchronized(initializers) {
            if (initializer != null) {
                return initializers.put(cb, initializer);
            } else {

View on GitHub (pinned to d036ad9781)

Solutions

  1. Confirm the class exists: 'unzip -l jna.jar | grep DLLCallback'; if missing, replace the jar with a complete official jna.jar release.
  2. 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.
  3. 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).
  4. As a diagnostic, run a tiny program calling Class.forName("com.sun.jna.win32.DLLCallback") with the same classpath to isolate classloader problems.

Example fix

// before (Windows startup)
java.lang.ExceptionInInitializerError
  Caused by: java.lang.Error: Error loading DLLCallback class
  Caused by: java.lang.ClassNotFoundException: com.sun.jna.win32.DLLCallback
// after (maven: single aligned version)
<dependency><groupId>net.java.dev.jna</groupId><artifactId>jna</artifactId><version>5.14.0</version></dependency>
<dependency><groupId>net.java.dev.jna</groupId><artifactId>jna-platform</artifactId><version>5.14.0</version></dependency>
Defensive patterns

Strategy: validation

Validate before calling

// early check on Windows hosts
if (Platform.isWindows()) {
    try {
        Class.forName("com.sun.jna.win32.DLLCallback");
    } catch (ClassNotFoundException e) {
        throw new IllegalStateException("jna.jar missing win32 package", e);
    }
}

Try / catch

try { initJnaCallbacks(); } catch (ExceptionInInitializerError e) { throw new IllegalStateException("Incomplete JNA classpath (DLLCallback missing): " + e.getCause(), e); }

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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