{"record":{"id":"7ed6944313c3defd","repo":"cloudflare/cloudflared","slug":"error-determining-install-path","errorCode":null,"errorMessage":"Error determining install path","messagePattern":"Error determining install path","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/cloudflared/macos_service.go","lineNumber":155,"sourceCode":"\n\tif isRootUser() {\n\t\tlog.Info().Msg(\"Installing cloudflared client as a system launch daemon. \" +\n\t\t\t\"cloudflared client will run at boot\")\n\t} else {\n\t\tlog.Info().Msg(\"Installing cloudflared client as an user launch agent. \" +\n\t\t\t\"Note that cloudflared client will only run when the user is logged in. \" +\n\t\t\t\"If you want to run cloudflared client at boot, install with root permission. \" +\n\t\t\t\"For more information, visit https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/configure-tunnels/local-management/as-a-service/macos/\")\n\t}\n\tetPath, err := os.Executable()\n\tif err != nil {\n\t\tlog.Err(err).Msg(\"Error determining executable path\")\n\t\treturn fmt.Errorf(\"error determining executable path: %w\", err)\n\t}\n\tinstallPath, err := installPath()\n\tif err != nil {\n\t\tlog.Err(err).Msg(\"Error determining install path\")\n\t\treturn errors.Wrap(err, \"Error determining install path\")\n\t}\n\n\tvar extraArgs []string\n\tif c.NArg() > 0 {\n\t\t// The service has been installed using a token e.g.,\n\t\t// $ cloudflared service install <token>\n\t\t//\n\t\t// Write the token file to a config directory so we can start the\n\t\t// daemon with --token-file\n\n\t\t// Don't use :=, if we did so we would create a new err variable and\n\t\t// shadow the outer one, causing the defer below to not have access to\n\t\t// the outer err\n\t\tvar cp string\n\t\tcp, err = configPath()\n\t\tif err != nil {\n\t\t\tlog.Err(err).Msg(\"Error determining path to config directory\")\n\t\t\treturn err","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cmd/cloudflared/macos_service.go#L137-L173","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Ensure $HOME is set and points to an existing directory before running the install (e.g. `sudo -H cloudflared service install ...`).","Verify the executing user exists and has a valid home directory (`dscl . -read /Users/<name> NFSHomeDirectory` on macOS).","Run `cloudflared service install` from an interactive login shell rather than a stripped cron/CI environment.","As root, /Library/LaunchDaemons is used and homedir is not consulted — install as root to bypass home-dir resolution."],"exampleFix":"// before (in CI/docker where HOME is unset)\ncloudflared service install <token>\n\n// after\nexport HOME=$(eval echo ~${SUDO_USER:-$USER}) && cloudflared service install <token>","handlingStrategy":"validation","validationCode":"if [ -z \"$HOME\" ] || [ ! -d \"$HOME\" ]; then echo \"HOME must be set to an existing directory\"; exit 1; fi","typeGuard":null,"tryCatchPattern":"err := cmd.Run(); if strings.Contains(err.Error(), \"determining install path\") { fixHomeEnvAndRetry() }","preventionTips":["Always install with `sudo -H` so HOME matches the invoking user","Check $HOME exists in provisioning scripts before service install","Prefer root install (LaunchDaemons) in automation to skip homedir lookup","Verify user accounts have valid home directories before deploying"],"tags":["macos","launchd","home-directory","service-install"],"backgroundTag":"missing-env-var","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}