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

Failed to start the service

Error message

Failed to start the service

What it means

Raised by Puppet::Util::Windows::Service.start when StartServiceW returns FALSE after the service handle was opened and its state validated. StartServiceW fails for concrete Win32 reasons: the service is disabled, a dependency failed to start, access denied (handle opened without SERVICE_START), or the service is marked for deletion. The appended Win32 text and e.code identify which.

Source

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

    end
    module_function :exists?

    # Start a windows service
    #
    # @param [String] service_name name of the service to start
    # @param optional [Integer] timeout the minumum number of seconds to wait before timing out
    def start(service_name, timeout: DEFAULT_TIMEOUT)
      Puppet.debug _("Starting the %{service_name} service. Timeout set to: %{timeout} seconds") % { service_name: service_name, timeout: timeout }

      valid_initial_states = [
        SERVICE_STOP_PENDING,
        SERVICE_STOPPED,
        SERVICE_START_PENDING
      ]

      transition_service_state(service_name, valid_initial_states, SERVICE_RUNNING, timeout) do |service|
        if StartServiceW(service, 0, FFI::Pointer::NULL) == FFI::WIN32_FALSE
          raise Puppet::Util::Windows::Error, _("Failed to start the service")
        end
      end

      Puppet.debug _("Successfully started the %{service_name} service") % { service_name: service_name }
    end
    module_function :start

    # Stop a windows service
    #
    # @param [String] service_name name of the service to stop
    # @param optional [Integer] timeout the minumum number of seconds to wait before timing out
    def stop(service_name, timeout: DEFAULT_TIMEOUT)
      Puppet.debug _("Stopping the %{service_name} service. Timeout set to: %{timeout} seconds") % { service_name: service_name, timeout: timeout }

      valid_initial_states = SERVICE_STATES.keys - [SERVICE_STOPPED]

      transition_service_state(service_name, valid_initial_states, SERVICE_STOPPED, timeout) do |service|
        send_service_control_signal(service, SERVICE_CONTROL_STOP)

View on GitHub (pinned to e227c27540)

Solutions

1. Check e.code: 1058 = service disabled, 1068 = dependency failure, 1072 = marked for deletion, 5 = access denied
2. Set the startup type to enabled (e.g. set_startup_configuration with :SERVICE_AUTO_START or manual) before calling start
3. Ensure dependency services are running first, or subscribe/require them in the manifest
4. Run from an elevated context with rights to start the service

Example fix

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

# after
Puppet::Util::Windows::Service.set_startup_configuration('myservice', startup_type: :SERVICE_DEMAND_START)
Puppet::Util::Windows::Service.start('myservice')

raise Puppet::Error, 'service missing' unless Puppet::Util::Windows::Service.exists?(name)
start_type = Puppet::Util::Windows::Service.service_start_type(name)
if start_type == :SERVICE_DISABLED
  Puppet::Util::Windows::Service.set_startup_configuration(name, startup_type: :SERVICE_DEMAND_START)
end

begin
  Puppet::Util::Windows::Service.start(name)
rescue Puppet::Error => e
  # detail in message carries the win32 cause; e.g. 1058 disabled, 1068 dependency
  raise Puppet::Error, "start(#{name}) failed: #{e.message}" 
end

When it happens

Trigger: Calling start on a service whose start type is SERVICE_DISABLED (error 1058), whose dependencies are not running (1068), on a service marked for deletion (1072), or when the process token lacks the service-start right (5). Also fires if the service binary itself fails to launch.

Common situations: Manifest sets ensure => running but the service's enable/start-type was left disabled and not changed in the same run; ordering issues where a dependency service is not yet up; agents running under accounts without permission to start the service.

Related errors

• Unknown Service state '%{current_state}' for '%{service_name
• Unknown start type '%{start_type}' for '%{service_name}'
• Failed to update service configuration
• Failed to fetch services
• Failed to open a handle to the service

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