java-native-access/jna · error · Win32Exception

Win32Exception from native GetLastError after SetThreadPrior

Error message

Win32Exception from native GetLastError after SetThreadPriority failed

What it means

setCurrentThreadPriority(int) throws this Win32Exception when the priority value is valid but the native SetThreadPriority call returns FALSE, with the message carrying GetLastError(). Common native error codes include ERROR_INVALID_PARAMETER (background-mode constants used incorrectly) and ERROR_ACCESS_DENIED.

Source

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

        final int nPriority = Kernel32.INSTANCE.GetThreadPriority(Kernel32.INSTANCE.GetCurrentThread());
        if (!isValidThreadPriority(nPriority)) {
            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
        }
        return nPriority;
    }

    /**
     * Sets the priority value for the current thread.
     *
     * @param nPriority The priority value for the thread.
     * @throws Win32Exception if an error occurs.
     */
    public static void setCurrentThreadPriority(final int nPriority) {
        if (!isValidThreadPriority(nPriority)) {
            throw new IllegalArgumentException("The given priority value is invalid!");
        }
        if (!Kernel32.INSTANCE.SetThreadPriority(Kernel32.INSTANCE.GetCurrentThread(), nPriority)) {
            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
        }
    }

    /**
     * Enables or disables "background" processing mode for the current thread
     *
     * @param enable If true, enables "background" processing mode, otherwise disables it.
     * @throws Win32Exception if an error occurs.
     */
    public static void setCurrentThreadBackgroundMode(final boolean enable) {
        // Note: THREAD_MODE_BACKGROUND_{BEGIN,END} only works with the "current" thread handle!
        final int nPriority = enable ? Kernel32.THREAD_MODE_BACKGROUND_BEGIN : Kernel32.THREAD_MODE_BACKGROUND_END;
        if (!Kernel32.INSTANCE.SetThreadPriority(Kernel32.INSTANCE.GetCurrentThread(), nPriority)) {
            throw new Win32Exception(Kernel32.INSTANCE.GetLastError());
        }
    }

    /**

View on GitHub (pinned to d036ad9781)

Solutions

Inspect Win32Exception.getErrorCode() to identify the native failure (5=access denied, 87=invalid parameter).
Operate on the current thread via Kernel32.INSTANCE.GetCurrentThread() pseudo-handle, which normally permits priority changes.
Wrap in try-catch and degrade to the previous priority on failure.
Ensure the thread is not in a state/job that forbids priority changes; avoid passing background-mode constants here.

Example fix

// before
Kernel32Util.setCurrentThreadPriority(WinBase.THREAD_PRIORITY_HIGHEST);
// after
try {
    Kernel32Util.setCurrentThreadPriority(WinBase.THREAD_PRIORITY_HIGHEST);
} catch (Win32Exception e) {
    LOG.warn("SetThreadPriority failed (" + e.getErrorCode() + "), keeping current priority");
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (!Kernel32Util.isValidThreadPriority(nPriority)) {
    throw new IllegalArgumentException("invalid thread priority");
}

Try / catch

try {
    Kernel32Util.setCurrentThreadPriority(nPriority);
} catch (Win32Exception e) {
    if (e.getErrorCode() == WinError.ERROR_ACCESS_DENIED) {
        log.warn("Thread priority change denied; keeping current priority");
    } else {
        throw e;
    }
}

Prevention

Set priorities only on the current thread (pseudo-handle) to avoid access-rights issues.
Treat priority changes as best-effort hints, not guarantees.
Check ERROR_ACCESS_DENIED (5) and ERROR_INVALID_PARAMETER (87) in logs.
Never pass THREAD_MODE_BACKGROUND_* constants to setCurrentThreadPriority.

When it happens

Trigger: Calling Kernel32Util.setCurrentThreadPriority() with a valid priority on a thread whose handle lacks THREAD_SET_INFORMATION rights, or passing THREAD_MODE_BACKGROUND_* constants to SetThreadPriority in a way the OS rejects.

Common situations: Modifying priorities of threads owned by other processes without rights; restricted tokens/services; job objects that disallow priority changes; misusing background-mode constants as priorities.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

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