cloudflare/cloudflared · error

error generating OpenRC conf.d template: %w

Error message

error generating OpenRC conf.d template: %w

What it means

Returned by installOpenRC (Gentoo/Alpine) when rendering the OpenRC conf.d template fails during Linux service installation. cloudflared generates /etc/conf.d/cloudflared from a Go template using the install arguments; a template generation error means the template could not be created or written, so the service files are incomplete and installation stops before rc-update.

Source

Thrown at cmd/cloudflared/linux_service.go:427

		}
	}
	for _, i := range [...]string{"0", "1", "6"} {
		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

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Run the install as root: `sudo cloudflared service install`.
2. Ensure /etc/conf.d exists and is writable (mkdir -p /etc/conf.d; check mount is not read-only).
3. Remove any broken existing /etc/conf.d/cloudflared file and retry.
4. Verify the binary path and ExtraArgs arguments passed to service install are valid (no empty --path values).
5. Check the wrapped error (%w cause) in the message for the precise filesystem failure.

Example fix

# before
$ cloudflared service install
# ERROR: error generating OpenRC conf.d template: open /etc/conf.d/cloudflared: permission denied

# after
$ sudo cloudflared service install

// Shell preflight before OpenRC install
[ "$(id -u)" -eq 0 ] || { echo "need root"; exit 1; }
mkdir -p /etc/conf.d && touch /etc/conf.d/.wtest && rm /etc/conf.d/.wtest || { echo "/etc/conf.d not writable"; exit 1; }

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

When it happens

Trigger: `cloudflared service install` on an OpenRC-based system where openrcConfTemplate.Generate(templateArgs) fails — typically the target conf.d file/directory is not writable (missing root), a filesystem error, or bad template arguments (e.g. empty ExtraArgs or invalid cloudflaredBinaryPath).

Common situations: Installing without sudo on Gentoo/Alpine so /etc/conf.d is unwritable; corrupted or manually-modified /etc/conf.d/cloudflared; read-only root filesystem on minimal containers running OpenRC.

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 service 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/423d8b9543cdabcf. Report an issue: GitHub.