nats-io/nats-server · error

failed to get home dir, require $HOME

Error message

failed to get home dir, require $HOME

What it means

homeDir() on non-Windows platforms: the HOME environment variable is empty, so the home directory cannot be resolved for relative paths such as config or pid files. The unset $HOME is the input at fault.

Source

Thrown at server/opts.go:6608

func homeDir() (string, error) {
	if runtime.GOOS == "windows" {
		homeDrive, homePath := os.Getenv("HOMEDRIVE"), os.Getenv("HOMEPATH")
		userProfile := os.Getenv("USERPROFILE")

		home := filepath.Join(homeDrive, homePath)
		if homeDrive == _EMPTY_ || homePath == _EMPTY_ {
			if userProfile == _EMPTY_ {
				return _EMPTY_, errors.New("nats: failed to get home dir, require %HOMEDRIVE% and %HOMEPATH% or %USERPROFILE%")
			}
			home = userProfile
		}

		return home, nil
	}

	home := os.Getenv("HOME")
	if home == _EMPTY_ {
		return _EMPTY_, errors.New("failed to get home dir, require $HOME")
	}
	return home, nil
}

func expandPath(p string) (string, error) {
	p = os.ExpandEnv(p)

	if !strings.HasPrefix(p, "~") {
		return p, nil
	}

	home, err := homeDir()
	if err != nil {
		return _EMPTY_, err
	}

	return filepath.Join(home, p[1:]), nil
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Export HOME in the shell or service environment
2. Use absolute paths for -c/-P and similar file options
3. For systemd units, set Environment=HOME=... in the unit file

When it happens

Trigger: Thrown at server/opts.go:6608 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/fd4add26ef01317a. Report an issue: GitHub.