java-native-access/jna · error · IllegalArgumentException

Unrecognized calling convention: <convention>

Error message

Unrecognized calling convention: <convention>

What it means

JNA validates that the calling convention value fits within the allowed MASK_CC bits. Passing a convention value with bits outside the mask (or a convention the current build doesn't recognize) throws IllegalArgumentException. Per-platform validation is otherwise not performed.

Source

Thrown at src/com/sun/jna/Function.java:292

    Function(Pointer functionAddress, int callFlags, String encoding) {
        checkCallingConvention(callFlags & MASK_CC);
        if (functionAddress == null
            || functionAddress.peer == 0) {
            throw new NullPointerException("Function address may not be null");
        }
        this.functionName = functionAddress.toString();
        this.callFlags = callFlags;
        this.peer = functionAddress.peer;
        this.options = Collections.EMPTY_MAP;
        this.encoding = encoding != null
            ? encoding : Native.getDefaultStringEncoding();
    }

    private void checkCallingConvention(int convention)
        throws IllegalArgumentException {
        // TODO: perform per-platform calling convention checks
        if ((convention & MASK_CC) != convention) {
            throw new IllegalArgumentException("Unrecognized calling convention: "
                                               + convention);
        }
    }

    public String getName() {
        return functionName;
    }

    public int getCallingConvention() {
        return callFlags & MASK_CC;
    }

    /** Invoke the native function with the given arguments, returning the
     * native result as an Object.
     */
    public Object invoke(Class<?> returnType, Object[] inArgs) {
        return invoke(returnType, inArgs, this.options);
    }

View on GitHub (pinned to d036ad9781)

Solutions

1. Use only the predefined constants Function.C_CONVENTION or Function.ALT_CONVENTION appropriate to your platform
2. Remove the CALLING_CONVENTION option/function argument so the platform default is used
3. Verify the platform supports the convention (ALT_CONVENTION is primarily Windows stdcall)

Example fix

// before
new Function(lib, "f", 0x7FFF); // bogus convention
// after
new Function(lib, "f", Function.C_CONVENTION);

int cc = convention & Function.MASK_CC;
if (cc != convention) throw new IllegalArgumentException("bad convention " + convention);
if (cc != Function.C_CONVENTION && cc != Function.ALT_CONVENTION) throw new IllegalArgumentException("unknown convention");

try {
    f.invoke(method, types, ret, args, opts);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unrecognized calling convention")) { /* fix option */ }
}

When it happens

Trigger: Passing Function.ALT_CONVENTION or a custom integer to a Function constructor or invoke() option where MASK_CC doesn't include that value; mixing conventions across platforms.

Common situations: Using stdcall (ALT_CONVENTION) on platforms where only CDECL is valid; hand-crafted convention constants copied from other libraries; typo'd option values.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• The given priority value is invalid!
• must be set from byte[]
• Unsupported return type <returnType> in function <name>
• Function <name> declared Structure[] at parameter <index> bu
• Function <name> declared Structure[] at parameter <index> bu

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