{"record":{"id":"66b67bf34e3f4b5d","repo":"java-native-access/jna","slug":"timeout-waiting-for-service-to-change-to-a-non-pending-state","errorCode":null,"errorMessage":"Timeout waiting for service to change to a non-pending state.","messagePattern":"Timeout waiting for service to change to a non-pending state\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"contrib/platform/src/com/sun/jna/platform/win32/W32Service.java","lineNumber":333,"sourceCode":"     */\n    public void waitForNonPendingState() {\n\n        SERVICE_STATUS_PROCESS status = queryStatus();\n\n        int previousCheckPoint = status.dwCheckPoint;\n        int checkpointStartTickCount = Kernel32.INSTANCE.GetTickCount();\n\n        while (isPendingState(status.dwCurrentState)) {\n\n            // if the checkpoint advanced, start new tick count\n            if (status.dwCheckPoint != previousCheckPoint) {\n                previousCheckPoint = status.dwCheckPoint;\n                checkpointStartTickCount = Kernel32.INSTANCE.GetTickCount();\n            }\n\n            // if the time that passed is greater than the wait hint - throw timeout exception\n            if (Kernel32.INSTANCE.GetTickCount() - checkpointStartTickCount > status.dwWaitHint) {\n                throw new RuntimeException(\"Timeout waiting for service to change to a non-pending state.\");\n            }\n\n            int dwWaitTime = sanitizeWaitTime(status.dwWaitHint);\n\n            try {\n                Thread.sleep(dwWaitTime);\n            } catch (InterruptedException e) {\n                throw new RuntimeException(e);\n            }\n\n            status = queryStatus();\n        }\n    }\n\n    private boolean isPendingState(int state) {\n        switch (state) {\n            case Winsvc.SERVICE_CONTINUE_PENDING:\n            case Winsvc.SERVICE_STOP_PENDING:","sourceCodeStart":315,"sourceCodeEnd":351,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/platform/src/com/sun/jna/platform/win32/W32Service.java#L315-L351","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nservice.startService(); // throws if slow start exceeds wait hint\n// after\ntry {\n    service.startService();\n} catch (RuntimeException e) {\n    // poll queryStatus() manually until desired state or a longer deadline\n}","handlingStrategy":"try-catch","validationCode":"Winsvc.SERVICE_STATUS st = service.queryStatus();\nboolean pending = st.dwCurrentState == Winsvc.SERVICE_START_PENDING\n    || st.dwCurrentState == Winsvc.SERVICE_STOP_PENDING;\n// if pending with a small dwWaitHint, expect possible timeouts","typeGuard":null,"tryCatchPattern":"try {\n    service.startService();\n} catch (RuntimeException timeout) {\n    Winsvc.SERVICE_STATUS st = service.queryStatus();\n    // poll manually with your own, longer deadline\n}","preventionTips":["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."],"tags":["windows","service","timeout"],"backgroundTag":"request-timeout","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}