cloudflare/cloudflared · error

error generating OpenRC service template: %w

Error message

error generating OpenRC service template: %w

What it means

Returned by installOpenRC when rendering the OpenRC service (init.d) template fails after the conf.d template succeeded. cloudflared generates /etc/init.d/cloudflared from a Go template; failure here leaves the service unregistered and installation aborts before rc-update add runs.

Source

Thrown at cmd/cloudflared/linux_service.go:430

		if err := os.Symlink(confPath, "/etc/rc"+i+".d/K02et"); err != nil {
			continue
		}
	}
	return runCommand("service", "cloudflared", "start")
}

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")

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Run the install as root: `sudo cloudflared service install`.
2. Ensure /etc/init.d exists and is writable; remove or fix any non-file at /etc/init.d/cloudflared.
3. Confirm the root filesystem is writable (mount checks in containers/chroots).
4. Inspect the wrapped cause (%w) for the exact underlying error and address it.
5. After a successful install, register manually if needed: rc-update add cloudflared default && rc-service cloudflared start.

Example fix

# before
$ cloudflared service install
# ERROR: error generating OpenRC service template: mkdir /etc/init.d: read-only file system

# after
$ sudo mount -o remount,rw /
$ sudo cloudflared service install

// Shell preflight before OpenRC install
[ "$(id -u)" -eq 0 ] || { echo "need root"; exit 1; }
[ ! -d /etc/init.d/cloudflared ] || { echo "/etc/init.d/cloudflared is a directory"; exit 1; }
touch /etc/init.d/.wtest 2>/dev/null && rm /etc/init.d/.wtest || { echo "/etc/init.d not writable"; exit 1; }

// Go
out, err := exec.Command("cloudflared", "service", "install").CombinedOutput()
if err != nil && strings.Contains(string(out), "error generating OpenRC service template") {
    return fmt.Errorf("OpenRC init.d template generation failed; check /etc/init.d permissions: %s", out)
}

When it happens

Trigger: `cloudflared service install` on an OpenRC-based system where openrcTemplate.Generate(templateArgs) fails — unwritable /etc/init.d, existing non-regular file at the target path, filesystem error, or invalid template arguments (cloudflaredBinaryPath/ExtraArgs).

Common situations: Installing without root on Gentoo/Alpine; /etc/init.d/cloudflared exists as a directory or is immutable; read-only root filesystem (containers, live systems); disk full while writing the init script.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• error generating OpenRC conf.d template: %w
• rc-update add %s default: %w
• configuration file %s must contain entries for the tunnel to
• possible conflicting configuration in %[1]s and %[2]s. Eithe
• failed to copy %s to %s: %w

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