java-native-access/jna · error · IllegalArgumentException

No mapping for %02x

Error message

No mapping for %02x

What it means

Win32VK.fromValue(int) scans the VK enum constants for a matching virtual-key code and throws this IllegalArgumentException when no constant matches. It is a strict lookup: any code not modeled by the enum (OEM-specific, vendor-extended, or reserved codes) is rejected.

Solutions

1. Validate/sanitize the code before lookup; treat unmatched codes as unhandled keys rather than failures.
2. Wrap in try-catch and fall back to raw-code handling.
3. Upgrade the JNA version, which may add newer VK constants.
4. Verify you are passing a virtual-key code, not a scancode (scancode conversion requires MapVirtualKey).

Example fix

// before
Win32VK vk = Win32VK.fromValue(code); // throws for unknown codes
// after
Win32VK vk;
try {
    vk = Win32VK.fromValue(code);
} catch (IllegalArgumentException e) {
    vk = null; // handle unknown key via raw code
}

if (code < 0 || code > 0xFF) throw new IllegalArgumentException("not a VK code: " + code);

static Win32VK tryFromValue(int code) {
    try { return Win32VK.fromValue(code); }
    catch (IllegalArgumentException e) { return null; }
}

try {
    Win32VK vk = Win32VK.fromValue(code);
    handle(vk);
} catch (IllegalArgumentException unknown) {
    handleRawCode(code);
}

When it happens

Trigger: Calling Win32VK.fromValue with a virtual-key code absent from the enum — e.g. nonstandard OEM keys (0xA6–0xAC range gaps), vendor-defined codes, or raw keyboard scancodes mistakenly passed as VK codes.

Common situations: Parsing WM_KEYDOWN lParam into VK codes from unusual keyboards/layouts; international keyboard layouts producing codes not in the enum; passing 0 or garbage values from uninitialized message structures.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The query's property enum has no values.
• Can't open X Display
• Could not set proxy blanket.
• DACL is invalid
• destDir must be a directory.

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

Appendix: source

Thrown at contrib/platform/src/com/sun/jna/platform/win32/Win32VK.java:443

    private Win32VK(int code) {
        this(code, 0);
    }

    /**
     * This will return the first of the multiple VK constants mapped to the same
     * value. First as defined in the order of the header file listing the
     * constants.
     *
     * @param code the code value.
     * @return the VK enum instance.
     */
    public static Win32VK fromValue(final int code) {
        for (Win32VK vk : Win32VK.values()) {
            if (vk.code == code) {
                return vk;
            }
        }
        throw new IllegalArgumentException(String.format("No mapping for %02x", code));
    }
}

View on GitHub (pinned to d036ad9781)