{"record":{"id":"c8bed2252d578785","repo":"puppetlabs/puppet","slug":"unexpected-transition-to-the-current-state-stat","errorCode":null,"errorMessage":"Unexpected transition to the %{current_state} state while waiting for the pending transition from %{pending_state} to %{final_state} to finish.","messagePattern":"Unexpected transition to the %(.+?) state while waiting for the pending transition from %(.+?) to %(.+?) to finish\\.","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/util/windows/service.rb","lineNumber":653,"sourceCode":"      # @param [Integer] timeout the minumum number of seconds to wait before timing out\n      def wait_on_pending_state(service, pending_state, timeout)\n        final_state = FINAL_STATES[pending_state]\n\n        Puppet.debug _(\"Waiting for the pending transition to the %{final_state} state to finish.\") % { final_state: SERVICE_STATES[final_state] }\n\n        elapsed_time = 0\n        last_checkpoint = -1\n        loop do\n          query_status(service) do |status|\n            state = status[:dwCurrentState]\n            checkpoint = status[:dwCheckPoint]\n            wait_hint = status[:dwWaitHint]\n            # Check if our service has finished transitioning to\n            # the final_state OR if an unexpected transition\n            # has occurred\n            return if state == final_state\n            unless state == pending_state\n              raise Puppet::Error, _(\"Unexpected transition to the %{current_state} state while waiting for the pending transition from %{pending_state} to %{final_state} to finish.\") % { current_state: SERVICE_STATES[state], pending_state: SERVICE_STATES[pending_state], final_state: SERVICE_STATES[final_state] }\n            end\n\n            # Check if any progress has been made since our last sleep\n            # using the dwCheckPoint. If no progress has been made then\n            # check if we've timed out, and raise an error if so\n            if checkpoint > last_checkpoint\n              elapsed_time = 0\n              last_checkpoint = checkpoint\n            else\n              wait_hint = milliseconds_to_seconds(status[:dwWaitHint])\n              timeout = wait_hint < timeout ? timeout : wait_hint\n\n              if elapsed_time >= timeout\n                raise Puppet::Error, _(\"Timed out while waiting for the pending transition from %{pending_state} to %{final_state} to finish. The current state is %{current_state}.\") % { pending_state: SERVICE_STATES[pending_state], final_state: SERVICE_STATES[final_state], current_state: SERVICE_STATES[state] }\n              end\n            end\n            wait_time = wait_hint_to_wait_time(wait_hint)\n            # Wait a bit before rechecking the service's state","sourceCodeStart":635,"sourceCodeEnd":671,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/util/windows/service.rb#L635-L671","documentation":"Raised by wait_on_pending_state when, while waiting for a service to complete a pending transition (e.g. START_PENDING -> RUNNING), QueryServiceStatusEx reports a state that is neither the pending state nor the final state. This means the service jumped somewhere unexpected — most commonly it crashed or was stopped while starting, so the state went to STOPPED instead of RUNNING.","triggerScenarios":"Service process dies during ServiceMain (dependency missing, crash in init) so the SCM records STOPPED while Puppet waits for RUNNING; someone (or another agent) explicitly stops the service during its START_PENDING window; a service fails fast and flips to STOPPED after a brief pause.","commonSituations":"Service binary fails to start due to a bad config file or missing DLL — it never reaches RUNNING; concurrent management (SCCM/another Puppet run) stopping the service mid-transition; watchdog software killing the process during startup.","solutions":["Check why the service left the pending state: Windows Application/System event log, the service's own log — usually a crash (missing DLL, bad config, port in use).","Start the service manually (`net start <name>` or `sc start <name>`) to reproduce and read the immediate error.","Remove whatever is concurrently stopping/starting the service (second config-management tool, scheduled script).","Fix the service's startup failure (repair installation, correct configuration) rather than retrying the transition.","Re-run Puppet only after the root cause is fixed; otherwise the same crash recurs."],"exampleFix":"# before\nPuppet::Util::Windows::Service.start(service_name) # raises 'Unexpected transition to the stopped state...'\n\n# after - surface the service's own failure reason\nbegin\n  Puppet::Util::Windows::Service.start(service_name)\nrescue Puppet::Error => e\n  Puppet.err(\"#{service_name} did not reach RUNNING; last SCM events: \" +\n    `powershell -Command \"Get-WinEvent -FilterHashtable @{LogName='System'; ProviderName='Service Control Manager'} -MaxEvents 5 | Format-List Message\"`)\n  raise\nend","handlingStrategy":"try-catch","validationCode":"# smoke-test that the service can start at all before managing transitions\nok = system(\"net start #{name} >nul 2>&1\")\nraise \"#{name} cannot start; fix the service first\" unless ok || $?.exitstatus == 0","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::Util::Windows::Service.start(name)\nrescue Puppet::Error => e\n  raise unless e.message =~ /Unexpected transition to the (stopped|paused) state/\n  # service died mid-start: dump SCM events and re-raise with context\n  events = `powershell -Command \"Get-WinEvent -FilterHashtable @{LogName='System'} -MaxEvents 10 | ? Message -match '#{name}' | % Message\"`\n  raise \"#{name} crashed during start. Recent SCM events:\\n#{events}\"\nend","preventionTips":["Validate the service starts manually before putting it under automation.","Remove concurrent stoppers (watchdogs, second management tools) that fight the transition.","Monitor the service's own error log for startup failures (missing DLLs, config errors, port conflicts)."],"tags":["windows","win32","service","state-transition","crash-during-start","puppet"],"backgroundTag":"service-state-transition-failed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}