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

Failed to open a handle to the service

Error message

Failed to open a handle to the service

What it means

Raised by the private open_service helper when OpenServiceW returns a null handle. Almost always means the service does not exist under that name (ERROR_SERVICE_DOES_NOT_EXIST), or the caller lacks the requested service access rights. Every public Service method funnels through this helper, so the error surfaces from start/stop/service_state/etc. on missing services.

Source

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

      # corresponding to service_name
      #
      # this function takes a block that executes within the context of
      # the open service handler, and will close the service and SCManager
      # handles once the block finishes
      #
      # @param [string] service_name the name of the service to open
      # @param [Integer] scm_access code corresponding to the access type requested for the scm
      # @param [Integer] service_access code corresponding to the access type requested for the service
      # @yieldparam [:handle] service the windows native handle used to access
      #   the service
      # @return the result of the block
      def open_service(service_name, scm_access, service_access, &block)
        service = FFI::Pointer::NULL_HANDLE

        result = nil
        open_scm(scm_access) do |scm|
          service = OpenServiceW(scm, wide_string(service_name), service_access)
          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

View on GitHub (pinned to e227c27540)

Solutions

1. Guard with Puppet::Util::Windows::Service.exists?(service_name) first (it rescues ERROR_SERVICE_DOES_NOT_EXIST itself)
2. Confirm the exact service (not display) name with sc.exe or Get-Service
3. Fix resource ordering so the package/install step completes before service management
4. Check e.code: 1060 = service does not exist, 5 = access denied

Example fix

// before
Puppet::Util::Windows::Service.start('myservice')

# after
if Puppet::Util::Windows::Service.exists?('myservice')
  Puppet::Util::Windows::Service.start('myservice')
else
  Puppet.warning "Service 'myservice' is not installed"
end

unless Puppet::Util::Windows::Service.exists?(service_name)
  raise Puppet::Error, "Service '#{service_name}' is not installed"
end
Puppet::Util::Windows::Service.start(service_name)

begin
  Puppet::Util::Windows::Service.service_state(service_name)
rescue Puppet::Util::Windows::Error => e
  raise Puppet::Error, "Service not found: #{service_name}" if e.code == 1060 # ERROR_SERVICE_DOES_NOT_EXIST
  raise
end

When it happens

Trigger: Calling any Puppet::Util::Windows::Service API with a misspelled or not-yet-installed service name; referencing a service whose installation failed earlier in the run; requesting an access mask (e.g. SERVICE_ALL_ACCESS) the token does not hold.

Common situations: Manifest ordering: a service resource references a service that its package resource has not installed yet; name mismatches between display name and service name; uninstall races where the service was removed mid-run.

Related errors

• Unknown Service state '%{current_state}' for '%{service_name
• Unknown start type '%{start_type}' for '%{service_name}'
• Failed to fetch services
• Failed to open a handle to the service control manager
• 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/cc49e18b78f5107c. Report an issue: GitHub.