java-native-access/jna · error · com.sun.jna.platform.win32.COM.COMException

Error occured when trying to query for interface <comInterfa

Error message

Error occured when trying to query for interface <comInterface.getName()>

What it means

Generic wrapper COMException from ProxyObject.queryInterface() for any non-COMException RuntimeException thrown while querying for the interface. The requested interface's class name is included in the message and the real exception is preserved as the cause. It signals an unexpected failure (not a plain failed HRESULT) during the QI process.

Source

Thrown at contrib/platform/src/com/sun/jna/platform/win32/COM/util/ProxyObject.java:509

            if (WinNT.S_OK.equals(hr)) {
                Dispatch dispatch = new Dispatch(ppvObject.getValue());
                T t = this.factory.createProxy(comInterface, dispatch);
                // QueryInterface returns a COM object pointer with a +1
                // reference, we must drop one,
                // Note: createProxy adds one;
                int n = dispatch.Release();
                return t;
            } else {
                String formatMessageFromHR = Kernel32Util.formatMessage(hr);
                throw new COMException("queryInterface: " + formatMessageFromHR, hr);
            }
        } catch (RuntimeException e) {
            // Do not rewrap COMException
            if (e instanceof COMException) {
                throw e;
            } else {
                throw new COMException("Error occured when trying to query for interface " + comInterface.getName(), e);
            }
        }
    }

    private IID getIID(ComInterface annotation) {
        String iidStr = annotation.iid();
        if (null != iidStr && !iidStr.isEmpty()) {
            return new IID(iidStr);
        } else {
            throw new COMException("ComInterface must define a value for iid");
        }
    }

    // --------------------- ProxyObject ---------------------

    private String getAccessorName(java.lang.reflect.Method method, ComProperty prop) {
        if (prop.name().isEmpty()) {
            String methName = method.getName();

View on GitHub (pinned to d036ad9781)

Solutions

1. Read getCause() to identify the true RuntimeException
2. Ensure the proxy is still alive and used from its creating thread/apartment
3. Verify the queried interface extends IUnknown and its methods map to valid COM signatures
4. Catch COMException around queryInterface when probing optional interfaces

Example fix

// before
Foo foo = proxy.queryInterface(Foo.class); // after release
// after
if (!isReleased(proxy)) {
    Foo foo = proxy.queryInterface(Foo.class);
}

if (!comInterface.isAnnotationPresent(ComInterface.class)) throw new IllegalArgumentException("missing @ComInterface");

boolean qiSafe = proxy != null && comInterface.isAnnotationPresent(ComInterface.class);

try { Foo f = proxy.queryInterface(Foo.class); } catch (COMException e) { LOG.error("queryInterface for " + Foo.class.getName() + " failed", e.getCause()); }

When it happens

Trigger: RuntimeExceptions during queryInterface — e.g. NPE from a null internal dispatch after release, ClassCastException building the typed proxy, or errors resolving the interface's methods against the returned pointer.

Common situations: Using a proxy whose dispatch was disposed; interface class with methods that cannot be mapped to the COM vtable; annotation/iid inconsistencies triggering secondary failures.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• Error occured when trying get Unknown Id
• getUnknownId: <formatMessageFromHR>
• Error occured in advise when trying to connect the listener
• Error occured in unadvise when trying to disconnect the list
• queryInterface: Interface must define a value for iid via th

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