cloudflare/cloudflared · error

Cannot determine home directory for the user

Error message

Cannot determine home directory for the user

What it means

On macOS, resolveLibraryPath computes paths under ~/Library using go-homedir. "Cannot determine home directory for the user" wraps homedir.Dir() failures, so cloudflared cannot resolve install/log/config paths for the user-level service. The comment notes this is unreliable when running under sudo, since $HOME may be altered.

Source

Thrown at cmd/cloudflared/macos_service.go:108

func isRootUser() bool {
	return os.Geteuid() == 0
}

func resolveLibraryPath(subPath, fileName string) (string, error) {
	const libraryDirName = "Library"

	// We use the system-wide /Library/... instead of ~/Library/... if the user is root
	if isRootUser() {
		return filepath.Join("/", libraryDirName, subPath, fileName), nil
	}

	// This returns the home dir of the executing user using OS-specific method
	// for discovering the home dir. It's not recommended to call this when the
	// user has root permission as $HOME depends on what options the user uses
	// with sudo.
	userHomeDir, err := homedir.Dir()
	if err != nil {
		return "", errors.Wrap(err, "Cannot determine home directory for the user")
	}
	return filepath.Join(userHomeDir, libraryDirName, subPath, fileName), nil
}

// For docs on these subdirectories, see:
// https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html
func installPath() (string, error) {
	subpath := "LaunchAgents"
	if isRootUser() {
		subpath = "LaunchDaemons"
	}
	return resolveLibraryPath(subpath, launchdIdentifier+".plist")
}

func stdoutPath() (string, error) {
	return resolveLibraryPath("Logs", launchdIdentifier+".out.log")
}

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Ensure $HOME is set and correct: run `echo $HOME`; when using sudo, add `sudo -H` so HOME resolves to the invoking user's directory.
2. Run the service install as a normal user with a valid login shell, or install system-wide where homedir isn't needed.
3. If HOME is genuinely unset, export it (e.g., export HOME=$(cd ~; pwd)) before invoking cloudflared.
4. Verify the executing user exists in /etc/passwd/dscl with a valid home directory.

Example fix

// before
sudo cloudflared service install
// after
sudo -H cloudflared service install

if os.Getenv("HOME") == "" {
	return errors.New("$HOME is not set; run as a normal user or use sudo -H")
}

p, err := resolveLibraryPath("config.json")
if err != nil {
	log.Err(err).Msgf("cannot resolve macOS library path: %+v", err)
	return err
}

When it happens

Trigger: Running `cloudflared service install` (or any path via installPath/stdoutPath/stderrPath/configPath) on macOS when homedir.Dir() fails: $HOME unset and no passwd entry, or homedir lookup failing due to sudo/sandboxed environments.

Common situations: Installing the service via sudo where HOME points nowhere; running inside CI containers or LaunchDaemons without a login user; deleted/mismatched passwd entries for the executing user.

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 install path
• error determining executable path: %w
• error resolving path %s: %v
• error determining stdout path
• error determining stderr path

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