{"record":{"id":"c85058a9e20208bc","repo":"puppetlabs/puppet","slug":"timed-out-while-waiting-for-the-service-to-transit","errorCode":null,"errorMessage":"Timed out while waiting for the service to transition from %{initial_state} to %{final_state} OR from %{initial_state} to %{pending_state} to %{final_state}. The service's current state is %{current_state}.","messagePattern":"Timed out while waiting for the service to transition from %(.+?) to %(.+?) OR from %(.+?) to %(.+?) to %(.+?)\\. The service's current state is %(.+?)\\.","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/util/windows/service.rb","lineNumber":624,"sourceCode":"            state = status[:dwCurrentState]\n            return if state == final_state\n\n            if state == pending_state\n              Puppet.debug _(\"The service transitioned to the %{pending_state} state.\") % { pending_state: SERVICE_STATES[pending_state] }\n              wait_on_pending_state(service, pending_state, timeout)\n              return\n            end\n            sleep(1)\n            elapsed_time += 1\n          end\n        end\n        # Timed out while waiting for the transition to finish. Raise an error\n        # We can still use the state variable read from the FFI struct because\n        # FFI creates new Integer objects during an assignment of an integer value\n        # stored in an FFI struct. We verified that the '=' operater is safe\n        # from the freed memory since the new ruby object created during the\n        # assignment will remain in ruby memory and remain immutable and constant.\n        raise Puppet::Error, _(\"Timed out while waiting for the service to transition from %{initial_state} to %{final_state} OR from %{initial_state} to %{pending_state} to %{final_state}. The service's current state is %{current_state}.\") % { initial_state: SERVICE_STATES[initial_state], final_state: SERVICE_STATES[final_state], pending_state: SERVICE_STATES[pending_state], current_state: SERVICE_STATES[state] }\n      end\n      private :wait_on_state_transition\n\n      # @api private\n      # Waits for a service to finish transitioning from\n      # a pending state. The service must be in the pending state\n      # before invoking this routine.\n      #\n      # @param [:handle] service handle to the service to wait on\n      # @param [Integer] pending_state the pending state\n      # @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","sourceCodeStart":606,"sourceCodeEnd":642,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/util/windows/service.rb#L606-L642","documentation":"Raised by wait_on_state_transition when a service does not reach the requested final state within the timeout (DEFAULT_TIMEOUT = 30 seconds, overridable via the timeout: keyword of Service.start/stop/resume, which is what the Windows service provider passes). The message records the from/to states, the intermediate pending state, and the state observed at timeout. It is a Puppet::Error (not a Win32 error) raised after polling with 1-second sleeps.","triggerScenarios":"Service.start/stop/resume on a service that takes longer than 30 seconds to move (e.g. START_PENDING -> RUNNING); slow shutdown with long shutdown timeouts in the service binary; the service is waiting on a dependency (RPC endpoint mapper, SQL) that is itself slow; heavy load lengthening start beyond the default.","commonSituations":"Large services (SQL Server, Antivirus, backup agents) on slow VMs; first boot after patching when many services start concurrently; services that block in ServiceMain waiting on network resources; Puppet runs failing transiently during startup storms.","solutions":["Pass a larger timeout to the API call: Puppet::Util::Windows::Service.start(service_name, timeout: 120) — the Windows service provider already forwards this pattern.","Measure how long the service actually needs (`sc query` in a loop, or the service's own logs) and set the timeout above that.","Fix the service's slowness: reduce work in ServiceMain, declare/start dependencies first, or increase the service's own dwWaitHint so the SCM does not kill it.","Retry the Puppet run — startup-time spikes during boot or patching are often transient.","Check the application/system event log for the service to see what it was doing when the timeout fired."],"exampleFix":"# before\nPuppet::Util::Windows::Service.start(service_name) # waits max 30s (DEFAULT_TIMEOUT)\n\n# after\nPuppet::Util::Windows::Service.start(service_name, timeout: 180) # allow slow-starting service","handlingStrategy":"retry","validationCode":"# measure the service's real start time before choosing a timeout\nstarted = Time.now\n`sc start #{name}`\nsleep 1 until `sc query #{name}` =~ /RUNNING/ || Time.now - started > 30\n# set your Puppet timeout comfortably above the observed duration","typeGuard":null,"tryCatchPattern":"attempts = 0\nbegin\n  attempts += 1\n  Puppet::Util::Windows::Service.start(name, timeout: 120)\nrescue Puppet::Error => e\n  raise unless e.message.include?('Timed out') && attempts < 3\n  Puppet.warning(\"start timeout, retry #{attempts}/3\")\n  retry\nend","preventionTips":["Pass an explicit timeout: to Service.start/stop/resume sized to the slowest realistic start (default is 30s).","Reduce startup work in the service itself and declare service dependencies so prerequisites start first.","Expect first-boot/patch-window runs to be slow; schedule retries rather than failing hard."],"tags":["windows","win32","service","timeout","start-pending","puppet"],"backgroundTag":"service-operation-timeout","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}