What causes "cannot find user-specific home dir" in wtfutil/wtf?

Ensure the runtime user has a valid passwd entry with a home directory (add the user or use useradd)

cannot find user-specific home dir

Error message

cannot find user-specific home dir

What it means

home() resolves the current OS user's home directory via user.Current(). If the OS reports the user but with an empty HomeDir, this error is thrown because no path can be returned. It is the underlying failure of expandHomeDir for all '~'-prefixed config paths.

Source

Thrown at cfg/config_files.go:195

	}

	dir, err := home()
	if err != nil {
		return "", err
	}

	return filepath.Join(dir, path[1:]), nil
}

// Dir returns the home directory for the executing user.
// An error is returned if a home directory cannot be detected.
func home() (string, error) {
	currentUser, err := user.Current()
	if err != nil {
		return "", err
	}
	if currentUser.HomeDir == "" {
		return "", errors.New("cannot find user-specific home dir")
	}

	return currentUser.HomeDir, nil
}

// migrateOldConfig copies any existing configuration from the old location
// to the new, XDG-compatible location
func migrateOldConfig() {
	srcDir, _ := expandHomeDir(WtfConfigDirV1)
	destDir, _ := WtfConfigDir()

	// If the old config directory doesn't exist, do not move
	if _, err := os.Stat(srcDir); os.IsNotExist(err) {
		return
	}

	// If the new config directory already exists, do not move
	if _, err := os.Stat(destDir); err == nil {

View on GitHub (pinned to bb838c1ccb)

Solutions

Ensure the runtime user has a valid passwd entry with a home directory (add the user or use useradd)
Set HOME and check `go env`/build flags: build with CGO_ENABLED=1 or use an image with proper nsswitch files
Avoid '~' paths: pass an absolute config path explicitly (WTF_CONFIG env var or -c flag)
Run as a normal user account instead of an arbitrary UID

Example fix

# before
USER 10001  # no passwd entry, HomeDir empty
# after
RUN useradd -m appuser
USER appuser

Defensive patterns

Strategy: fallback

Validate before calling

u, err := user.Current()
if err != nil || u.HomeDir == "" {
    // don't rely on ~ expansion; set WTF_CONFIG or pass absolute path
}

Type guard

func homeDirAvailable() bool {
    u, err := user.Current()
    return err == nil && u.HomeDir != ""
}

Try / catch

if _, err := cfg.LoadWtfConfigFile("~/.config/wtf/config.yml"); err != nil {
    if strings.Contains(err.Error(), "cannot find user-specific home") {
        cfgPath = os.Getenv("WTF_CONFIG") // fallback
    }
}

Prevention

In containers, create the runtime user with a home directory (useradd -m)
Avoid CGO_ENABLED=0 static builds if OS user lookup matters, or set HOME explicitly
Set WTF_CONFIG to an absolute path in minimal environments
Smoke-test user.Current().HomeDir in your image before launch

When it happens

Trigger: Running in an environment where user.Current() succeeds but HomeDir is empty — e.g. misconfigured /etc/passwd entry, containers running as a UID with no passwd entry, CGO disabled with missing getent data, or stripped-down scratch/Distroless images.

Common situations: Docker containers running as non-root numeric UIDs without passwd entries; CI sandboxes with unset/mangled user records; cross-compiled static Go binaries (CGO_ENABLED=0) on minimal images where user lookup returns empty HomeDir.

Related errors

AI-assisted analysis of wtfutil/wtf@bb838c1ccb (2026-09-03). Data as JSON: /api/errors/3be7fcedea873244. Report an issue: GitHub.