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

ComInterface must define a value for iid

Error message

ComInterface must define a value for iid

What it means

This variant fires when the @ComInterface annotation IS present but its iid() attribute is null or empty. createRIID needs a valid GUID string to build the REFIID used for COM event advising. A present-but-empty iid is a configuration mistake inside the annotation itself.

Source

Thrown at contrib/platform/src/com/sun/jna/platform/win32/COM/util/CallbackProxy.java:97

        this.dispatchListener = new DispatchListener(this);
    }

    ObjectFactory factory;
    Class<?> comEventCallbackInterface;
    IComEventCallbackListener comEventCallbackListener;
    REFIID listenedToRiid;
    public DispatchListener dispatchListener;
    Map<DISPID, Method> dsipIdMap;

    private REFIID createRIID(Class<?> comEventCallbackInterface) {
        ComInterface comInterfaceAnnotation = comEventCallbackInterface.getAnnotation(ComInterface.class);
        if (null == comInterfaceAnnotation) {
            throw new COMException(
                    "advise: Interface must define a value for either iid via the ComInterface annotation");
        }
        String iidStr = comInterfaceAnnotation.iid();
        if (null == iidStr || iidStr.isEmpty()) {
            throw new COMException("ComInterface must define a value for iid");
        }
        return new REFIID(new IID(iidStr).getPointer());
    }

    @SuppressWarnings("deprecation") // ComEventCallback is used here to be backwards compatible
    private Map<DISPID, Method> createDispIdMap(Class<?> comEventCallbackInterface) {
        Map<DISPID, Method> map = new HashMap<>();

        for (Method meth : comEventCallbackInterface.getMethods()) {
            ComEventCallback callbackAnnotation = meth.getAnnotation(ComEventCallback.class);
            ComMethod methodAnnotation = meth.getAnnotation(ComMethod.class);
            if (methodAnnotation != null) {
                int dispId = methodAnnotation.dispId();
                if (-1 == dispId) {
                    dispId = this.fetchDispIdFromName(callbackAnnotation);
                }
                if (dispId == -1) {
                    CallbackProxy.this.comEventCallbackListener.errorReceivingCallbackEvent(

View on GitHub (pinned to d036ad9781)

Solutions

1. Set @ComInterface(iid="{valid-guid}") with the real IID from the type library
2. Look the IID up with a tool such as OLE/COM Object Viewer or the .tlb contents
3. Validate the GUID string format before runtime (new IID(iidStr) will also fail on malformed GUIDs)

Example fix

// before
@ComInterface
public interface IApplicationEvents extends IComEventCallbackListener { ... }
// after
@ComInterface(iid = "{61A762AF-3C1E-4B0C-9A1F-5E1F0E14C9F2}")
public interface IApplicationEvents extends IComEventCallbackListener { ... }

ComInterface a = iface.getAnnotation(ComInterface.class);
if (a == null || a.iid() == null || a.iid().isEmpty())
    throw new IllegalArgumentException(iface.getName() + " must set @ComInterface(iid=...)");

try { factory.addEventListener(iface, method, listener); } catch (COMException e) { if (e.getMessage().contains("value for iid")) { /* supply iid */ } }

When it happens

Trigger: Declaring @ComInterface without the iid attribute (or with iid = "") on an interface used as a COM event callback; building the annotation dynamically and leaving iid unset.

Common situations: Copying an @ComInterface declaration from another interface and forgetting to fill in the new GUID; using a placeholder that was never replaced; annotation defined with only the value attribute while code reads iid().

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• advise: Interface must define a value for either iid via the
• createObject: Interface must define a value for either clsId
• ComObject must define a value for either clsId or progId
• advise: Interface must define a value for either iid via the
• unadvise: Interface must define a value for iid via the ComI

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