java-native-access/jna · error · java.lang.RuntimeException

Property Mutator name must start with 'set', or set the anot

Error message

Property Mutator name must start with 'set', or set the anotation 'name' value

What it means

This RuntimeException is thrown by ProxyObject.getMutatorName when a @ComProperty-annotated method is used as a property mutator but the annotation's 'name' attribute is empty and the Java method name does not start with 'set'. JNA strips the 'set' prefix to derive the COM property name, so it cannot proceed without either convention or an explicit name.

Source

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

            String methName = method.getName();
            if (methName.startsWith("get")) {
                return methName.replaceFirst("get", "");
            } else {
                throw new RuntimeException(
                        "Property Accessor name must start with 'get', or set the anotation 'name' value");
            }
        } else {
            return prop.name();
        }
    }

    private String getMutatorName(java.lang.reflect.Method method, ComProperty prop) {
        if (prop.name().isEmpty()) {
            String methName = method.getName();
            if (methName.startsWith("set")) {
                return methName.replaceFirst("set", "");
            } else {
                throw new RuntimeException(
                        "Property Mutator name must start with 'set', or set the anotation 'name' value");
            }
        } else {
            return prop.name();
        }
    }

    private String getMethodName(java.lang.reflect.Method method, ComMethod meth) {
        if (meth.name().isEmpty()) {
            String methName = method.getName();
            return methName;
        } else {
            return meth.name();
        }
    }

    @SuppressWarnings("deprecation")
    protected DISPID resolveDispId(String name) {

View on GitHub (pinned to d036ad9781)

Solutions

1. Rename the method to start with 'set' (e.g. setValue)
2. Set the 'name' attribute of @ComProperty explicitly: @ComProperty(name = "PropName")
3. Check that the property write path (invokePropertyPut) uses getMutatorName on the intended method

Example fix

// before
@ComProperty
public void assignValue(String value);
// after
@ComProperty(name = "Value")
public void assignValue(String value);

java.lang.reflect.Method m = ...;
ComProperty prop = m.getAnnotation(ComProperty.class);
if (prop != null && prop.name().isEmpty() && !m.getName().startsWith("set")) {
    throw new IllegalArgumentException(m.getName() + " must start with 'set' or set @ComProperty(name=...)");
}

boolean isValidMutator(java.lang.reflect.Method m) {
    ComProperty p = m.getAnnotation(ComProperty.class);
    return p == null || (!p.name().isEmpty() || m.getName().startsWith("set"));
}

When it happens

Trigger: Declaring a @ComProperty mutator method whose name does not start with 'set' (e.g. 'assignValue(String v)') with no name in the annotation, then invoking it through the COM proxy.

Common situations: Custom naming in hand-written COM binding interfaces; refactoring renamed setX to something else; copy-pasted methods annotated as properties without adjusting names.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Property Accessor name must start with 'get', or set the ano
• advise: Interface must define a value for either iid via the
• ComInterface must define a value for iid
• createObject: Interface must define a value for either clsId
• ComObject must define a value for either clsId or progId

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