{"record":{"id":"a17cf3bb39d20ee3","repo":"java-native-access/jna","slug":"pdisp-idispatch-parameter-is-null","errorCode":null,"errorMessage":"pDisp (IDispatch) parameter is null!","messagePattern":"pDisp \\(IDispatch\\) parameter is null!","errorType":"exception","errorClass":"COMException","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/win32/COM/COMBindingBaseObject.java","lineNumber":325,"sourceCode":"\n        return this.oleMethod(nType, pvResult, name, (VARIANT[]) null);\n    }\n\n    protected HRESULT oleMethod(int nType, VARIANT.ByReference pvResult,\n            DISPID dispId) throws COMException {\n\n        return this.oleMethod(nType, pvResult, dispId, (VARIANT[]) null);\n    }\n\n    /**\n     * @deprecated {@link COMBindingBaseObject#oleMethod(int, com.sun.jna.platform.win32.Variant.VARIANT.ByReference, java.lang.String, com.sun.jna.platform.win32.Variant.VARIANT[]) }\n     */\n    @Deprecated\n    protected HRESULT oleMethod(int nType, VARIANT.ByReference pvResult,\n            IDispatch pDisp, String name, VARIANT[] pArgs) throws COMException {\n\n        if (pDisp == null)\n            throw new COMException(\"pDisp (IDispatch) parameter is null!\");\n\n        // variable declaration\n        WString[] ptName = new WString[] { new WString(name) };\n        DISPIDByReference pdispID = new DISPIDByReference();\n\n        // Get DISPID for name passed...\n        HRESULT hr = pDisp.GetIDsOfNames(new REFIID(Guid.IID_NULL), ptName, 1,\n                LOCALE_USER_DEFAULT, pdispID);\n\n        COMUtils.checkRC(hr);\n\n        return this\n                .oleMethod(nType, pvResult, pDisp, pdispID.getValue(), pArgs);\n    }\n\n    /**\n     * @deprecated {@link COMBindingBaseObject#oleMethod(int, com.sun.jna.platform.win32.Variant.VARIANT.ByReference, com.sun.jna.platform.win32.OaIdl.DISPID, com.sun.jna.platform.win32.Variant.VARIANT[]) }\n     */","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/win32/COM/COMBindingBaseObject.java#L307-L343","documentation":"The deprecated COMBindingBaseObject.oleMethod(int, VARIANT.ByReference, IDispatch, String, VARIANT[]) overload requires a non-null IDispatch pointer because it invokes IDispatch::GetIDsOfNames and ::Invoke on it. A COMException is thrown immediately when the dispatch pointer is null, before any COM call is made.","triggerScenarios":"Calling oleMethod with a pDisp argument that was never initialized, was released, or came from a failed CoCreateInstance/QueryInterface that returned null.","commonSituations":"Constructing an COMBindingBaseObject whose initialization failed silently and then calling methods via the null dispatch; storing the IDispatch in a field that is null until some lazy init ran; using the deprecated overloads after refactoring.","solutions":["Ensure the COM object was successfully created before calling oleMethod; check the IDispatch returned from the constructor or factory.","Switch to the non-deprecated oleMethod overloads on COMBindingBaseObject that use the internal dispatch pointer.","Add an explicit null check on your IDispatch handle before invoking.","Catch COMException and treat it as a programming error rather than a runtime condition."],"exampleFix":"// before\nbinding.oleMethod(COMUtils.DISPATCH_METHOD, result, possiblyNullDisp, \"ExecQuery\", args);\n// after\nif (possiblyNullDisp == null) throw new IllegalStateException(\"COM object not initialized\");\nbinding.oleMethod(COMUtils.DISPATCH_METHOD, result, possiblyNullDisp, \"ExecQuery\", args);","handlingStrategy":"type-guard","validationCode":"if (pDisp != null) { binding.oleMethod(nType, pvResult, pDisp, name, args); }","typeGuard":"boolean isInitialized(IDispatch d) { return d != null && d.getPointer() != null; }","tryCatchPattern":"try {\n    binding.oleMethod(nType, pvResult, pDisp, name, args);\n} catch (COMException e) {\n    if (\"pDisp (IDispatch) parameter is null!\".equals(e.getMessage())) { /* reinit COM object */ }\n}","preventionTips":["Check HRESULTs from COM object creation before use","Avoid deprecated oleMethod overloads; use instance methods","Null-check cached IDispatch fields after any Release()"],"tags":["windows","com","jna","null-check"],"backgroundTag":"null-argument","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"}