cloudflare/cloudflared · error

Error determining install path

Error message

Error determining install path

What it means

This error is wrapped when the launchd service installer cannot compute the absolute path of the .plist file it would install (~/Library/LaunchAgents or /Library/LaunchDeamons depending on whether the process runs as root). The underlying failure almost always comes from `homedir.Dir()` being unable to resolve the executing user's home directory, since `resolveLibraryPath` is the only failure point inside `installPath()`. cloudflared wraps and re-raises it so the user knows the service was not installed.

Source

Thrown at cmd/cloudflared/macos_service.go:155

	if isRootUser() {
		log.Info().Msg("Installing cloudflared client as a system launch daemon. " +
			"cloudflared client will run at boot")
	} else {
		log.Info().Msg("Installing cloudflared client as an user launch agent. " +
			"Note that cloudflared client will only run when the user is logged in. " +
			"If you want to run cloudflared client at boot, install with root permission. " +
			"For more information, visit https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/configure-tunnels/local-management/as-a-service/macos/")
	}
	etPath, err := os.Executable()
	if err != nil {
		log.Err(err).Msg("Error determining executable path")
		return fmt.Errorf("error determining executable path: %w", err)
	}
	installPath, err := installPath()
	if err != nil {
		log.Err(err).Msg("Error determining install path")
		return errors.Wrap(err, "Error determining install path")
	}

	var extraArgs []string
	if c.NArg() > 0 {
		// The service has been installed using a token e.g.,
		// $ cloudflared service install <token>
		//
		// Write the token file to a config directory so we can start the
		// daemon with --token-file

		// Don't use :=, if we did so we would create a new err variable and
		// shadow the outer one, causing the defer below to not have access to
		// the outer err
		var cp string
		cp, err = configPath()
		if err != nil {
			log.Err(err).Msg("Error determining path to config directory")
			return err

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Ensure $HOME is set and points to an existing directory before running the install (e.g. `sudo -H cloudflared service install ...`).
2. Verify the executing user exists and has a valid home directory (`dscl . -read /Users/<name> NFSHomeDirectory` on macOS).
3. Run `cloudflared service install` from an interactive login shell rather than a stripped cron/CI environment.
4. As root, /Library/LaunchDaemons is used and homedir is not consulted — install as root to bypass home-dir resolution.

Example fix

// before (in CI/docker where HOME is unset)
cloudflared service install <token>

// after
export HOME=$(eval echo ~${SUDO_USER:-$USER}) && cloudflared service install <token>

if [ -z "$HOME" ] || [ ! -d "$HOME" ]; then echo "HOME must be set to an existing directory"; exit 1; fi

err := cmd.Run(); if strings.Contains(err.Error(), "determining install path") { fixHomeEnvAndRetry() }

When it happens

Trigger: Running `cloudflared service install` on macOS when installPath() fails: `homedir.Dir()` returns an error because $HOME is unset/empty for the executing user, or the OS-specific home directory lookup fails (e.g. user has no home directory, or a stripped environment under sudo -i/su with a broken passwd entry).

Common situations: Running the install under sudo with $HOME pointing at a nonexistent directory; running from a launch script or CI where HOME is not set; corrupted /etc/passwd or Directory Services entry for the user; running the binary as a non-login service account that has no home directory.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• error determining executable path: %w
• Cannot determine home directory for the user
• error determining stdout path
• error determining stderr path
• error determining install path

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