puppetlabs/puppet · error · Puppet::Util::Windows::Error

Failed to open a handle to the service control manager

Error message

Failed to open a handle to the service control manager

What it means

Raised by the private open_scm helper when OpenSCManagerW returns a null handle, meaning the service control manager could not be opened with the requested access. Typical Win32 causes are the SCM database being locked or the RPC server unavailable (SCM is reached over RPC), plus plain access denial for the requested mask. Every Service API that needs an SCM connection can surface it.

Source

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

          raise Puppet::Util::Windows::Error, _("Failed to open a handle to the service") if service == FFI::Pointer::NULL_HANDLE

          result = yield service
        end

        result
      ensure
        CloseServiceHandle(service)
      end
      private :open_service

      # @api private
      #
      # Opens a handle to the service control manager
      #
      # @param [Integer] scm_access code corresponding to the access type requested for the scm
      def open_scm(scm_access, &block)
        scm = OpenSCManagerW(FFI::Pointer::NULL, FFI::Pointer::NULL, scm_access)
        raise Puppet::Util::Windows::Error, _("Failed to open a handle to the service control manager") if scm == FFI::Pointer::NULL_HANDLE

        yield scm
      ensure
        CloseServiceHandle(scm)
      end
      private :open_scm

      # @api private
      # Transition the service to the specified state. The block should perform
      # the actual transition.
      #
      # @param [String] service_name the name of the service to transition
      # @param [[Integer]] valid_initial_states an array of valid states that the service can transition from
      # @param [Integer] final_state the state that the service will transition to
      # @param [Integer] timeout the minumum number of seconds to wait before timing out
      def transition_service_state(service_name, valid_initial_states, final_state, timeout, &block)
        service_access = SERVICE_START | SERVICE_STOP | SERVICE_PAUSE_CONTINUE | SERVICE_QUERY_STATUS
        open_service(service_name, SC_MANAGER_CONNECT, service_access) do |service|

View on GitHub (pinned to e227c27540)

Solutions

1. Read e.code: 1071 = database locked, 1722/1717 = RPC unavailable, 5 = access denied
2. Retry after a wait; SCM contention is usually transient
3. Delay service management until after boot/startup churn if this fires at startup
4. Run elevated to rule out SCM access restrictions

def with_scm_retry(tries: 3)
  yield
rescue Puppet::Util::Windows::Error => e
  retry if (tries -= 1) > 0 && [1071, 1717, 1722].include?(e.code) # locked / RPC down
  raise Puppet::Error, "SCM unreachable (code #{e.code})"
end

When it happens

Trigger: Any Puppet::Util::Windows::Service call while the SCM is busy (service database locked during installs), during early boot before RpcSs is ready, or from a token lacking the minimum SC_MANAGER_CONNECT right.

Common situations: Agent runs colliding with Windows Update / MSI service installs; boot-start scripts hitting the SCM too early; heavily loaded machines where SCM responses time out.

Related errors

• Failed to fetch services
• Unknown Service state '%{current_state}' for '%{service_name
• Unknown start type '%{start_type}' for '%{service_name}'
• Failed to open a handle to the service
• The service must be in one of the %{valid_initial_states} st

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