cloudflare/cloudflared · error

%s %v returned with error code %v due to: %v

Error message

%s %v returned with error code %v due to: %v

What it means

The service command executed but exited non-zero; runCommand returns the command, its args, exit code, and captured stderr. This is the standard failure mode when installing/uninstalling the cloudflared service via systemctl/service/rc-service.

Source

Thrown at cmd/cloudflared/service_template.go:106

		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)

Solutions

1. Run the command with root privileges (sudo cloudflared service install)
2. Read the 'due to:' portion of the message — it contains the actual stderr from systemctl/service/rc-service
3. Fix the reported unit/config problem (validate the service file, remove a stale unit, systemctl daemon-reload)
4. Check logs: journalctl -u cloudflared for systemd systems

Example fix

# before
cloudflared service install <token>
# after
sudo cloudflared service install <token>

if os.Geteuid() != 0 {
	return errors.New("installing the service requires root; rerun with sudo")
}

if err := runCommand("systemctl", "enable", "--now", serviceFile); err != nil {
	// err already embeds stderr output ('due to: ...')
	var exitErr *exec.ExitError
	if errors.As(err, &exitErr) {
		log.Debug().Int("code", exitErr.ExitCode()).Msg("service command exit")
	}
	return err
}

When it happens

Trigger: systemctl refuses to enable the unit (root required), the service file is invalid, the config token is bad, rc-service/service scripts reject the operation, or a name conflict exists (service already installed/uninstalled).

Common situations: Running 'cloudflared service install' without sudo; installing with an already-used service name; malformed /etc/systemd/system/cloudflared.service; SELinux or permission issues on the unit file.

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

• error getting stderr pipe: %v
• error starting %s: %v
• error retrieving output from command '%s': %w
• ErrUnauthorized
• ErrBadRequest

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