java-native-access/jna · error · IllegalArgumentException

The given priority value is invalid!

Error message

The given priority value is invalid!

What it means

setCurrentProcessPriority(DWORD) validates its argument with isValidPriorityClass() before touching the native API. If the given priority value is not one of the recognized Windows priority-class constants, it throws a plain IllegalArgumentException with the message "The given priority value is invalid!" rather than a Win32Exception, because the input never reached the OS.

Source

Thrown at contrib/platform/src/com/sun/jna/platform/win32/Kernel32Util.java:1283

     * @throws Win32Exception if an error occurs.
     */
    public static DWORD getCurrentProcessPriority() {
        final DWORD dwPriorityClass = Kernel32.INSTANCE.GetPriorityClass(Kernel32.INSTANCE.GetCurrentProcess());
        if (!isValidPriorityClass(dwPriorityClass)) {
            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
        }
        return dwPriorityClass;
    }

    /**
     * Sets the priority class for the current process.
     *
     * @param dwPriorityClass The priority class for the process.
     * @throws Win32Exception if an error occurs.
     */
    public static void setCurrentProcessPriority(final DWORD dwPriorityClass) {
        if (!isValidPriorityClass(dwPriorityClass)) {
            throw new IllegalArgumentException("The given priority value is invalid!");
        }
        if (!Kernel32.INSTANCE.SetPriorityClass(Kernel32.INSTANCE.GetCurrentProcess(), dwPriorityClass)) {
            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
        }
    }

    /**
     * Enables or disables "background" processing mode for the current process
     *
     * @param enable If true, enables "background" processing mode, otherwise disables it.
     * @throws Win32Exception if an error occurs.
     */
    public static void setCurrentProcessBackgroundMode(final boolean enable) {
        // Note: PROCESS_MODE_BACKGROUN_{BEGIN,END} only works with the "current" process handle!
        final DWORD dwPriorityClass = enable ? Kernel32.PROCESS_MODE_BACKGROUND_BEGIN : Kernel32.PROCESS_MODE_BACKGROUND_END;
        if (!Kernel32.INSTANCE.SetPriorityClass(Kernel32.INSTANCE.GetCurrentProcess(), dwPriorityClass)) {
            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
        }

View on GitHub (pinned to d036ad9781)

Solutions

1. Use the documented constants: Kernel32.NORMAL_PRIORITY_CLASS, HIGH_PRIORITY_CLASS, IDLE_PRIORITY_CLASS, REALTIME_PRIORITY_CLASS, BELOW_NORMAL_PRIORITY_CLASS, ABOVE_NORMAL_PRIORITY_CLASS.
2. Validate the value with Kernel32Util.isValidPriorityClass(dwPriorityClass) before calling setCurrentProcessPriority.
3. Do not pass thread priority values or background-mode constants to this API.
4. Check your code for mix-ups between setPriorityClass and setThreadPriority call sites.

Example fix

// before
Kernel32Util.setCurrentProcessPriority(new DWORD(5)); // thread-priority value, wrong API
// after
DWORD cls = Kernel32.HIGH_PRIORITY_CLASS;
if (Kernel32Util.isValidPriorityClass(cls)) {
    Kernel32Util.setCurrentProcessPriority(cls);
}

if (!Kernel32Util.isValidPriorityClass(dwPriorityClass)) {
    throw new IllegalArgumentException("Not a valid priority class: 0x" + Long.toHexString(dwPriorityClass.longValue()));
}

boolean isValidPriorityClassArg(DWORD v) {
    return v != null && Kernel32Util.isValidPriorityClass(v);
}

When it happens

Trigger: Passing a DWORD to Kernel32Util.setCurrentProcessPriority() that is not a valid priority class constant (e.g. 0, a thread-priority value like 5, or PROCESS_MODE_BACKGROUND_BEGIN passed by mistake when it is not valid standalone).

Common situations: Confusing thread priority values (-15..15) with process priority classes (IDLE=0x40, NORMAL=0x20, HIGH=0x80, REALTIME=0x100); hand-rolled constants; passing the background-mode constants outside their begin/end usage.

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

• Win32Exception from native GetLastError when GetPriorityClas
• Win32Exception from native GetLastError after SetPriorityCla
• Win32Exception from native GetLastError after SetPriorityCla
• Window must be a RootPaneContainer
• LookupAccountNameW was expected to fail with ERROR_INSUFFICI

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