{"record":{"id":"cc49e18b78f5107c","repo":"puppetlabs/puppet","slug":"failed-to-open-a-handle-to-the-service","errorCode":null,"errorMessage":"Failed to open a handle to the service","messagePattern":"Failed to open a handle to the service","errorType":"exception","errorClass":"Puppet::Util::Windows::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/util/windows/service.rb","lineNumber":308,"sourceCode":"      # corresponding to service_name\n      #\n      # this function takes a block that executes within the context of\n      # the open service handler, and will close the service and SCManager\n      # handles once the block finishes\n      #\n      # @param [string] service_name the name of the service to open\n      # @param [Integer] scm_access code corresponding to the access type requested for the scm\n      # @param [Integer] service_access code corresponding to the access type requested for the service\n      # @yieldparam [:handle] service the windows native handle used to access\n      #   the service\n      # @return the result of the block\n      def open_service(service_name, scm_access, service_access, &block)\n        service = FFI::Pointer::NULL_HANDLE\n\n        result = nil\n        open_scm(scm_access) do |scm|\n          service = OpenServiceW(scm, wide_string(service_name), service_access)\n          raise Puppet::Util::Windows::Error, _(\"Failed to open a handle to the service\") if service == FFI::Pointer::NULL_HANDLE\n\n          result = yield service\n        end\n\n        result\n      ensure\n        CloseServiceHandle(service)\n      end\n      private :open_service\n\n      # @api private\n      #\n      # Opens a handle to the service control manager\n      #\n      # @param [Integer] scm_access code corresponding to the access type requested for the scm\n      def open_scm(scm_access, &block)\n        scm = OpenSCManagerW(FFI::Pointer::NULL, FFI::Pointer::NULL, scm_access)\n        raise Puppet::Util::Windows::Error, _(\"Failed to open a handle to the service control manager\") if scm == FFI::Pointer::NULL_HANDLE","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/util/windows/service.rb#L290-L326","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Guard with Puppet::Util::Windows::Service.exists?(service_name) first (it rescues ERROR_SERVICE_DOES_NOT_EXIST itself)","Confirm the exact service (not display) name with sc.exe or Get-Service","Fix resource ordering so the package/install step completes before service management","Check e.code: 1060 = service does not exist, 5 = access denied"],"exampleFix":"// before\nPuppet::Util::Windows::Service.start('myservice')\n\n# after\nif Puppet::Util::Windows::Service.exists?('myservice')\n  Puppet::Util::Windows::Service.start('myservice')\nelse\n  Puppet.warning \"Service 'myservice' is not installed\"\nend","handlingStrategy":"validation","validationCode":"unless Puppet::Util::Windows::Service.exists?(service_name)\n  raise Puppet::Error, \"Service '#{service_name}' is not installed\"\nend\nPuppet::Util::Windows::Service.start(service_name)","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::Util::Windows::Service.service_state(service_name)\nrescue Puppet::Util::Windows::Error => e\n  raise Puppet::Error, \"Service not found: #{service_name}\" if e.code == 1060 # ERROR_SERVICE_DOES_NOT_EXIST\n  raise\nend","preventionTips":["Guard every Service call with exists? when the service may not be installed yet","Order manifest resources so packages install services before service resources run","Branch on e.code 1060 (not found) vs 5 (access denied)"],"tags":["windows","service","win32","scm","service-not-found"],"backgroundTag":"windows-service-not-found","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}