java-native-access/jna · error · COMException

pDisp (IDispatch) parameter is null!

Error message

pDisp (IDispatch) parameter is null!

What it means

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.

Source

Thrown at contrib/platform/src/com/sun/jna/platform/win32/COM/COMBindingBaseObject.java:325

        return this.oleMethod(nType, pvResult, name, (VARIANT[]) null);
    }

    protected HRESULT oleMethod(int nType, VARIANT.ByReference pvResult,
            DISPID dispId) throws COMException {

        return this.oleMethod(nType, pvResult, dispId, (VARIANT[]) null);
    }

    /**
     * @deprecated {@link COMBindingBaseObject#oleMethod(int, com.sun.jna.platform.win32.Variant.VARIANT.ByReference, java.lang.String, com.sun.jna.platform.win32.Variant.VARIANT[]) }
     */
    @Deprecated
    protected HRESULT oleMethod(int nType, VARIANT.ByReference pvResult,
            IDispatch pDisp, String name, VARIANT[] pArgs) throws COMException {

        if (pDisp == null)
            throw new COMException("pDisp (IDispatch) parameter is null!");

        // variable declaration
        WString[] ptName = new WString[] { new WString(name) };
        DISPIDByReference pdispID = new DISPIDByReference();

        // Get DISPID for name passed...
        HRESULT hr = pDisp.GetIDsOfNames(new REFIID(Guid.IID_NULL), ptName, 1,
                LOCALE_USER_DEFAULT, pdispID);

        COMUtils.checkRC(hr);

        return this
                .oleMethod(nType, pvResult, pDisp, pdispID.getValue(), pArgs);
    }

    /**
     * @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[]) }
     */

View on GitHub (pinned to d036ad9781)

Solutions

  1. Ensure the COM object was successfully created before calling oleMethod; check the IDispatch returned from the constructor or factory.
  2. Switch to the non-deprecated oleMethod overloads on COMBindingBaseObject that use the internal dispatch pointer.
  3. Add an explicit null check on your IDispatch handle before invoking.
  4. Catch COMException and treat it as a programming error rather than a runtime condition.

Example fix

// before
binding.oleMethod(COMUtils.DISPATCH_METHOD, result, possiblyNullDisp, "ExecQuery", args);
// after
if (possiblyNullDisp == null) throw new IllegalStateException("COM object not initialized");
binding.oleMethod(COMUtils.DISPATCH_METHOD, result, possiblyNullDisp, "ExecQuery", args);
Defensive patterns

Strategy: type-guard

Validate before calling

if (pDisp != null) { binding.oleMethod(nType, pvResult, pDisp, name, args); }

Type guard

boolean isInitialized(IDispatch d) { return d != null && d.getPointer() != null; }

Try / catch

try {
    binding.oleMethod(nType, pvResult, pDisp, name, args);
} catch (COMException e) {
    if ("pDisp (IDispatch) parameter is null!".equals(e.getMessage())) { /* reinit COM object */ }
}

Prevention

When it happens

Trigger: Calling oleMethod with a pDisp argument that was never initialized, was released, or came from a failed CoCreateInstance/QueryInterface that returned null.

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

Related errors

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