{"record":{"id":"5d947cbe59c9ca59","repo":"java-native-access/jna","slug":"error-occured-when-trying-to-query-for-interface","errorCode":null,"errorMessage":"Error occured when trying to query for interface <comInterface.getName()>","messagePattern":"Error occured when trying to query for interface <comInterface\\.getName\\(\\)>","errorType":"exception","errorClass":"com.sun.jna.platform.win32.COM.COMException","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/win32/COM/util/ProxyObject.java","lineNumber":509,"sourceCode":"\n            if (WinNT.S_OK.equals(hr)) {\n                Dispatch dispatch = new Dispatch(ppvObject.getValue());\n                T t = this.factory.createProxy(comInterface, dispatch);\n                // QueryInterface returns a COM object pointer with a +1\n                // reference, we must drop one,\n                // Note: createProxy adds one;\n                int n = dispatch.Release();\n                return t;\n            } else {\n                String formatMessageFromHR = Kernel32Util.formatMessage(hr);\n                throw new COMException(\"queryInterface: \" + formatMessageFromHR, hr);\n            }\n        } catch (RuntimeException e) {\n            // Do not rewrap COMException\n            if (e instanceof COMException) {\n                throw e;\n            } else {\n                throw new COMException(\"Error occured when trying to query for interface \" + comInterface.getName(), e);\n            }\n        }\n    }\n\n    private IID getIID(ComInterface annotation) {\n        String iidStr = annotation.iid();\n        if (null != iidStr && !iidStr.isEmpty()) {\n            return new IID(iidStr);\n        } else {\n            throw new COMException(\"ComInterface must define a value for iid\");\n        }\n    }\n\n    // --------------------- ProxyObject ---------------------\n\n    private String getAccessorName(java.lang.reflect.Method method, ComProperty prop) {\n        if (prop.name().isEmpty()) {\n            String methName = method.getName();","sourceCodeStart":491,"sourceCodeEnd":527,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/win32/COM/util/ProxyObject.java#L491-L527","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read getCause() to identify the true RuntimeException","Ensure the proxy is still alive and used from its creating thread/apartment","Verify the queried interface extends IUnknown and its methods map to valid COM signatures","Catch COMException around queryInterface when probing optional interfaces"],"exampleFix":"// before\nFoo foo = proxy.queryInterface(Foo.class); // after release\n// after\nif (!isReleased(proxy)) {\n    Foo foo = proxy.queryInterface(Foo.class);\n}","handlingStrategy":"try-catch","validationCode":"if (!comInterface.isAnnotationPresent(ComInterface.class)) throw new IllegalArgumentException(\"missing @ComInterface\");","typeGuard":"boolean qiSafe = proxy != null && comInterface.isAnnotationPresent(ComInterface.class);","tryCatchPattern":"try { Foo f = proxy.queryInterface(Foo.class); } catch (COMException e) { LOG.error(\"queryInterface for \" + Foo.class.getName() + \" failed\", e.getCause()); }","preventionTips":["Always inspect getCause() for wrapper exceptions","Don't QI on disposed proxies","Ensure interface methods map to valid COM signatures"],"tags":["com","queryinterface","wrapper","jni"],"backgroundTag":"api-request-failed","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}