java-native-access/jna · error · RuntimeException

Timeout waiting for service to change to a non-pending…

Error message

Timeout waiting for service to change to a non-pending state.

What it means

waitForNonPendingState() polls the service while it is in a pending state (START_PENDING, STOP_PENDING, etc.). Windows reports a dwWaitHint giving the expected time for the transition; if more time than the wait hint elapses without the checkpoint advancing, the library concludes the service is hung mid-transition and throws this RuntimeException.

Solutions

Fix the service to update dwCheckPoint periodically during long pending operations so the wait hint is honored.
Catch the RuntimeException and continue polling manually if the service is known to be slow but alive.
Increase the service's reported wait hint, or set the service's recovery actions.
Check service logs / Event Viewer to find why the transition never completes.

Example fix

// before
service.startService(); // throws if slow start exceeds wait hint
// after
try {
    service.startService();
} catch (RuntimeException e) {
    // poll queryStatus() manually until desired state or a longer deadline
}

Defensive patterns

Strategy: try-catch

Validate before calling

Winsvc.SERVICE_STATUS st = service.queryStatus();
boolean pending = st.dwCurrentState == Winsvc.SERVICE_START_PENDING
    || st.dwCurrentState == Winsvc.SERVICE_STOP_PENDING;
// if pending with a small dwWaitHint, expect possible timeouts

Try / catch

try {
    service.startService();
} catch (RuntimeException timeout) {
    Winsvc.SERVICE_STATUS st = service.queryStatus();
    // poll manually with your own, longer deadline
}

Prevention

Fix services to checkpoint regularly during long transitions.
Prefer your own deadline loop over trusting dwWaitHint for known-slow services.
Alert on services repeatedly timing out mid-transition.

When it happens

Trigger: Calling startService/stopService/pauseService/continueService on a service that stays in a pending state longer than its reported dwWaitHint without incrementing dwCheckPoint — e.g. a hung service binary or a service that never updates its status.

Common situations: Misbehaving service implementations that report START_PENDING forever; very slow service startup (DB connections, network mounts) exceeding its own wait hint; SCM reporting stale hints.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

Thrown at contrib/platform/src/com/sun/jna/platform/win32/W32Service.java:333

     */
    public void waitForNonPendingState() {

        SERVICE_STATUS_PROCESS status = queryStatus();

        int previousCheckPoint = status.dwCheckPoint;
        int checkpointStartTickCount = Kernel32.INSTANCE.GetTickCount();

        while (isPendingState(status.dwCurrentState)) {

            // if the checkpoint advanced, start new tick count
            if (status.dwCheckPoint != previousCheckPoint) {
                previousCheckPoint = status.dwCheckPoint;
                checkpointStartTickCount = Kernel32.INSTANCE.GetTickCount();
            }

            // if the time that passed is greater than the wait hint - throw timeout exception
            if (Kernel32.INSTANCE.GetTickCount() - checkpointStartTickCount > status.dwWaitHint) {
                throw new RuntimeException("Timeout waiting for service to change to a non-pending state.");
            }

            int dwWaitTime = sanitizeWaitTime(status.dwWaitHint);

            try {
                Thread.sleep(dwWaitTime);
            } catch (InterruptedException e) {
                throw new RuntimeException(e);
            }

            status = queryStatus();
        }
    }

    private boolean isPendingState(int state) {
        switch (state) {
            case Winsvc.SERVICE_CONTINUE_PENDING:
            case Winsvc.SERVICE_STOP_PENDING:

View on GitHub (pinned to d036ad9781)