cloudflare/cloudflared · error

error starting

Error message

error starting %s: %v

What it means

runCommand reports that the service-management command (systemctl, service, rc-service, etc.) could not be started. exec.Command's Start fails when the binary does not exist, is not in PATH, or lacks execute permission. The error names the command that failed.

Solutions

1. Verify the underlying init binary exists: which systemctl / which service / which rc-service
2. Install the init-system utilities for your distro (e.g. systemd, sysvinit-utils, openrc)
3. Use the installer matching your actual init system, or run cloudflared manually instead of as a service
4. Check PATH inside the environment where cloudflared runs

Example fix

// ensure the right init system binary is used
if _, err := exec.LookPath("systemctl"); err != nil {
	return errors.New("systemd not available on this host")
}
err := runCommand("systemctl", "enable", serviceFile)

if _, err := exec.LookPath("systemctl"); err != nil {
	return errors.New("systemctl not available; is this a systemd host?")
}

if err := runCommand("systemctl", "enable", serviceFile); err != nil {
	log.Warn().Err(err).Str("command", command).Msg("service command failed to start")
	return fmt.Errorf("service management unavailable: %w", err)
}

When it happens

Trigger: installSystemd/installSysv/installOpenRC or the corresponding uninstall functions invoke runCommand with a binary that is absent on the host (e.g. running the systemd installer on a system without systemd, or a stripped container image without /sbin/service).

Common situations: Running 'cloudflared service install' inside a minimal Docker image, on a distro without the expected init system utilities, or with a broken PATH in a systemd unit environment.

Related errors

• error getting stderr pipe
• returned with error code due to
• error retrieving output from command
• allowed mail rule is empty
• allowed mail rule has an invalid wildcard domain

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/b0adcc30dcf99dbb. Report an issue: GitHub.

Appendix: source

Thrown at cmd/cloudflared/service_template.go:100

func serviceAlreadyExistsWarn(service string) string {
	return fmt.Sprintf("cloudflared service is already installed at %s; if you are running a cloudflared tunnel, you "+
		"can point it to multiple origins, avoiding the need to run more than one cloudflared service in the "+
		"same machine; otherwise if you are really sure, you can do `cloudflared service uninstall` to clean "+
		"up the existing service and then try again this command",
		service,
	)
}

func runCommand(command string, args ...string) error {
	cmd := exec.Command(command, args...)
	stderr, err := cmd.StderrPipe()
	if err != nil {
		return fmt.Errorf("error getting stderr pipe: %v", err)
	}
	err = cmd.Start()
	if err != nil {
		return fmt.Errorf("error starting %s: %v", command, err)
	}

	output, _ := io.ReadAll(stderr)
	err = cmd.Wait()
	if err != nil {
		return fmt.Errorf("%s %v returned with error code %v due to: %v", command, args, err, string(output))
	}
	return nil
}

View on GitHub (pinned to 2253eeeb25)