{"record":{"id":"d85db06b6d2c1bd1","repo":"puppetlabs/puppet","slug":"failed-to-open-a-handle-to-the-service-control-man","errorCode":null,"errorMessage":"Failed to open a handle to the service control manager","messagePattern":"Failed to open a handle to the service control manager","errorType":"exception","errorClass":"Puppet::Util::Windows::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/util/windows/service.rb","lineNumber":326,"sourceCode":"          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\n\n        yield scm\n      ensure\n        CloseServiceHandle(scm)\n      end\n      private :open_scm\n\n      # @api private\n      # Transition the service to the specified state. The block should perform\n      # the actual transition.\n      #\n      # @param [String] service_name the name of the service to transition\n      # @param [[Integer]] valid_initial_states an array of valid states that the service can transition from\n      # @param [Integer] final_state the state that the service will transition to\n      # @param [Integer] timeout the minumum number of seconds to wait before timing out\n      def transition_service_state(service_name, valid_initial_states, final_state, timeout, &block)\n        service_access = SERVICE_START | SERVICE_STOP | SERVICE_PAUSE_CONTINUE | SERVICE_QUERY_STATUS\n        open_service(service_name, SC_MANAGER_CONNECT, service_access) do |service|","sourceCodeStart":308,"sourceCodeEnd":344,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/util/windows/service.rb#L308-L344","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read e.code: 1071 = database locked, 1722/1717 = RPC unavailable, 5 = access denied","Retry after a wait; SCM contention is usually transient","Delay service management until after boot/startup churn if this fires at startup","Run elevated to rule out SCM access restrictions"],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"def with_scm_retry(tries: 3)\n  yield\nrescue Puppet::Util::Windows::Error => e\n  retry if (tries -= 1) > 0 && [1071, 1717, 1722].include?(e.code) # locked / RPC down\n  raise Puppet::Error, \"SCM unreachable (code #{e.code})\"\nend","preventionTips":["Retry SCM opens with a delay; database locks and RPC hiccups resolve themselves","Do not run service management during early boot churn; schedule after startup","Run elevated to rule out SCM access restrictions"],"tags":["windows","service","win32","scm","rpc"],"backgroundTag":"windows-scm-unavailable","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}