{"record":{"id":"fb90128e2078e09e","repo":"java-native-access/jna","slug":"the-given-priority-value-is-invalid","errorCode":null,"errorMessage":"The given priority value is invalid!","messagePattern":"The given priority value is invalid!","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/win32/Kernel32Util.java","lineNumber":1283,"sourceCode":"     * @throws Win32Exception if an error occurs.\n     */\n    public static DWORD getCurrentProcessPriority() {\n        final DWORD dwPriorityClass = Kernel32.INSTANCE.GetPriorityClass(Kernel32.INSTANCE.GetCurrentProcess());\n        if (!isValidPriorityClass(dwPriorityClass)) {\n            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());\n        }\n        return dwPriorityClass;\n    }\n\n    /**\n     * Sets the priority class for the current process.\n     *\n     * @param dwPriorityClass The priority class for the process.\n     * @throws Win32Exception if an error occurs.\n     */\n    public static void setCurrentProcessPriority(final DWORD dwPriorityClass) {\n        if (!isValidPriorityClass(dwPriorityClass)) {\n            throw new IllegalArgumentException(\"The given priority value is invalid!\");\n        }\n        if (!Kernel32.INSTANCE.SetPriorityClass(Kernel32.INSTANCE.GetCurrentProcess(), dwPriorityClass)) {\n            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());\n        }\n    }\n\n    /**\n     * Enables or disables \"background\" processing mode for the current process\n     *\n     * @param enable If true, enables \"background\" processing mode, otherwise disables it.\n     * @throws Win32Exception if an error occurs.\n     */\n    public static void setCurrentProcessBackgroundMode(final boolean enable) {\n        // Note: PROCESS_MODE_BACKGROUN_{BEGIN,END} only works with the \"current\" process handle!\n        final DWORD dwPriorityClass = enable ? Kernel32.PROCESS_MODE_BACKGROUND_BEGIN : Kernel32.PROCESS_MODE_BACKGROUND_END;\n        if (!Kernel32.INSTANCE.SetPriorityClass(Kernel32.INSTANCE.GetCurrentProcess(), dwPriorityClass)) {\n            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());\n        }","sourceCodeStart":1265,"sourceCodeEnd":1301,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/win32/Kernel32Util.java#L1265-L1301","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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.","Validate the value with Kernel32Util.isValidPriorityClass(dwPriorityClass) before calling setCurrentProcessPriority.","Do not pass thread priority values or background-mode constants to this API.","Check your code for mix-ups between setPriorityClass and setThreadPriority call sites."],"exampleFix":"// before\nKernel32Util.setCurrentProcessPriority(new DWORD(5)); // thread-priority value, wrong API\n// after\nDWORD cls = Kernel32.HIGH_PRIORITY_CLASS;\nif (Kernel32Util.isValidPriorityClass(cls)) {\n    Kernel32Util.setCurrentProcessPriority(cls);\n}","handlingStrategy":"validation","validationCode":"if (!Kernel32Util.isValidPriorityClass(dwPriorityClass)) {\n    throw new IllegalArgumentException(\"Not a valid priority class: 0x\" + Long.toHexString(dwPriorityClass.longValue()));\n}","typeGuard":"boolean isValidPriorityClassArg(DWORD v) {\n    return v != null && Kernel32Util.isValidPriorityClass(v);\n}","tryCatchPattern":null,"preventionTips":["Only pass Kernel32.*_PRIORITY_CLASS constants to setCurrentProcessPriority.","Never pass thread priority values or background-mode constants to this API.","Validate with isValidPriorityClass at the call site before invoking.","Unit-test priority-setting code paths with only documented constants."],"tags":["jna","windows","argument-validation","process-priority","illegal-argument"],"backgroundTag":"invalid-argument-value","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}