cloudflare/cloudflared · error

rc-service %s start: %w

Error message

rc-service %s start: %w

What it means

This error wraps a failure from `rc-service cloudflared start` immediately after the OpenRC service is registered in the default runlevel. rc-service starts the service through OpenRC's init script; a non-zero exit means the service failed to launch. The wrapped error carries rc-service's output so the underlying cause (bad config, script failure) is visible.

Source

Thrown at cmd/cloudflared/linux_service.go:437

func installOpenRC(templateArgs *ServiceTemplateArgs, autoUpdate bool) error {
	if autoUpdate {
		templateArgs.ExtraArgs = append([]string{"--autoupdate-freq", "24h0m0s"}, templateArgs.ExtraArgs...)
	} else {
		templateArgs.ExtraArgs = append([]string{"--no-autoupdate"}, templateArgs.ExtraArgs...)
	}

	if err := openrcConfTemplate.Generate(templateArgs); err != nil {
		return fmt.Errorf("error generating OpenRC conf.d template: %w", err)
	}
	if err := openrcTemplate.Generate(templateArgs); err != nil {
		return fmt.Errorf("error generating OpenRC service template: %w", err)
	}

	if err := runCommand("rc-update", "add", cloudflaredOpenRCService, "default"); err != nil {
		return fmt.Errorf("rc-update add %s default: %w", cloudflaredOpenRCService, err)
	}
	if err := runCommand("rc-service", cloudflaredOpenRCService, "start"); err != nil {
		return fmt.Errorf("rc-service %s start: %w", cloudflaredOpenRCService, err)
	}
	return nil
}

func uninstallLinuxService(c *cli.Context) error {
	log := logger.CreateLoggerFromContext(c, logger.EnableTerminalLog)

	var err error
	switch {
	case inits.IsSystemd():
		log.Info().Msg("Using Systemd")
		err = uninstallSystemd(log)
	case inits.IsOpenRC():
		log.Info().Msg("Using OpenRC")
		err = uninstallOpenRC(log)
	default:
		log.Info().Msg("Using SysV")
		err = uninstallSysv(log)

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Start the service manually to see the error: `sudo rc-service cloudflared start` and read its output, or check /var/log/rc.log
2. Validate /etc/cloudflared/config.yml (or the token used at install time) — a common cause is invalid or missing tunnel credentials
3. Test the binary directly with the same args as the init script to reproduce the failure outside OpenRC
4. Remove stale state (pidfiles in /run) and retry: `sudo rc-service cloudflared zap` then start again
5. If the service is not needed at boot, skip install and run cloudflared directly (e.g. in a tmux session or container)

Example fix

// before: install fails at the start step due to bad config
$ sudo cloudflared service install
// error: rc-service cloudflared start: exit status 1
// after: verify config first, then install
$ sudo cloudflared tunnel --config /etc/cloudflared/config.yml run  # confirm it runs
$ sudo cloudflared service install

// validate the service can start before installing
func validateCloudflaredConfig() error {
    if _, err := os.Stat("/etc/cloudflared/config.yml"); err != nil {
        return fmt.Errorf("config missing, rc-service start will fail: %w", err)
    }
    return nil
}

func canStartService() bool {
    if _, err := exec.LookPath("rc-service"); err != nil { return false }
    if _, err := os.Stat("/etc/init.d/cloudflared"); err != nil { return false }
    return true
}

if err := installLinuxService(c); err != nil {
    if strings.Contains(err.Error(), "rc-service") {
        log.Warn("service registered but failed to start; inspect with: sudo rc-service cloudflared start; check /etc/cloudflared/config.yml and /var/log/rc.log")
    }
    return err
}

When it happens

Trigger: During `cloudflared service install` on OpenRC systems, when runCommand("rc-service", cloudflaredOpenRCService, "start") exits non-zero — e.g. invalid tunnel credentials in the config file, the init script exits with an error, or OpenRC itself is not functional.

Common situations: Missing or invalid /etc/cloudflared/config.yml (no tunnel token/credentials); cloudflared binary failing at startup due to bad flags baked into the init script; stale pidfile from a previous run; OpenRC reporting 'service started but not running' due to a crash on launch.

Related errors

• rc-update add %s default: %w
• error generating OpenRC conf.d template: %w
• error generating OpenRC service template: %w
• error resolving OpenRC template path: %w
• error removing %s: %w

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