puppetlabs/puppet · error · Puppet::Error

Unexpected transition to the %{current_state} state while wa

Error message

Unexpected transition to the %{current_state} state while waiting for the pending transition from %{pending_state} to %{final_state} to finish.

What it means

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.

Source

Thrown at lib/puppet/util/windows/service.rb:653

      # @param [Integer] timeout the minumum number of seconds to wait before timing out
      def wait_on_pending_state(service, pending_state, timeout)
        final_state = FINAL_STATES[pending_state]

        Puppet.debug _("Waiting for the pending transition to the %{final_state} state to finish.") % { final_state: SERVICE_STATES[final_state] }

        elapsed_time = 0
        last_checkpoint = -1
        loop do
          query_status(service) do |status|
            state = status[:dwCurrentState]
            checkpoint = status[:dwCheckPoint]
            wait_hint = status[:dwWaitHint]
            # Check if our service has finished transitioning to
            # the final_state OR if an unexpected transition
            # has occurred
            return if state == final_state
            unless state == pending_state
              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] }
            end

            # Check if any progress has been made since our last sleep
            # using the dwCheckPoint. If no progress has been made then
            # check if we've timed out, and raise an error if so
            if checkpoint > last_checkpoint
              elapsed_time = 0
              last_checkpoint = checkpoint
            else
              wait_hint = milliseconds_to_seconds(status[:dwWaitHint])
              timeout = wait_hint < timeout ? timeout : wait_hint

              if elapsed_time >= timeout
                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] }
              end
            end
            wait_time = wait_hint_to_wait_time(wait_hint)
            # Wait a bit before rechecking the service's state

View on GitHub (pinned to e227c27540)

Solutions

1. 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).
2. Start the service manually (`net start <name>` or `sc start <name>`) to reproduce and read the immediate error.
3. Remove whatever is concurrently stopping/starting the service (second config-management tool, scheduled script).
4. Fix the service's startup failure (repair installation, correct configuration) rather than retrying the transition.
5. Re-run Puppet only after the root cause is fixed; otherwise the same crash recurs.

Example fix

# before
Puppet::Util::Windows::Service.start(service_name) # raises 'Unexpected transition to the stopped state...'

# after - surface the service's own failure reason
begin
  Puppet::Util::Windows::Service.start(service_name)
rescue Puppet::Error => e
  Puppet.err("#{service_name} did not reach RUNNING; last SCM events: " +
    `powershell -Command "Get-WinEvent -FilterHashtable @{LogName='System'; ProviderName='Service Control Manager'} -MaxEvents 5 | Format-List Message"`)
  raise
end

# smoke-test that the service can start at all before managing transitions
ok = system("net start #{name} >nul 2>&1")
raise "#{name} cannot start; fix the service first" unless ok || $?.exitstatus == 0

begin
  Puppet::Util::Windows::Service.start(name)
rescue Puppet::Error => e
  raise unless e.message =~ /Unexpected transition to the (stopped|paused) state/
  # service died mid-start: dump SCM events and re-raise with context
  events = `powershell -Command "Get-WinEvent -FilterHashtable @{LogName='System'} -MaxEvents 10 | ? Message -match '#{name}' | % Message"`
  raise "#{name} crashed during start. Recent SCM events:\n#{events}"
end

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Service query for %{parameter_name} failed
• Failed to send the %{control_signal} signal to the service.
• Timed out while waiting for the service to transition from %
• Timed out while waiting for the pending transition from %{pe
• Passwords cannot include ':'

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/c8bed2252d578785. Report an issue: GitHub.