wtfutil/wtf · error

cannot expand user-specific home dir

Error message

cannot expand user-specific home dir

What it means

utils.ExpandHomeDir expands a leading tilde (~) in a path to the user's home directory. It only understands '~' or '~/...' (and '~\...' on Windows); any other form such as '~user/path' or '~foo' cannot be resolved, so it returns this error instead of guessing. It then uses os.UserHomeDir() to do the actual expansion.

Source

Thrown at utils/homedir.go:26

	"errors"
	"os"
	"path/filepath"
)

// ExpandHomeDir expands the path to include the home directory if the path
// is prefixed with `~`. If it isn't prefixed with `~`, the path is
// returned as-is.
func ExpandHomeDir(path string) (string, error) {
	if path == "" {
		return path, nil
	}

	if path[0] != '~' {
		return path, nil
	}

	if len(path) > 1 && path[1] != '/' && path[1] != '\\' {
		return "", errors.New("cannot expand user-specific home dir")
	}

	dir, err := os.UserHomeDir()
	if err != nil {
		return "", err
	}

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

View on GitHub (pinned to bb838c1ccb)

Solutions

1. Change the path to use '~/...' (tilde followed by a slash), e.g. '~/.config/wtf/config.yml'.
2. Use an absolute path (/home/user/...) if you truly need another user's home directory.
3. Expand the path yourself (via os/user lookup) before passing it to any WTFUtil API that calls ExpandHomeDir.

Example fix

// before
path := "~bob/config.yml" // error: cannot expand user-specific home dir

// after
path := "~/config.yml"        // expands to your own home
// or
path := "/home/bob/config.yml"

func validateTildePath(p string) error {
    if strings.HasPrefix(p, "~") && !strings.HasPrefix(p, "~/") && !strings.HasPrefix(p, "~\\") && p != "~" {
        return fmt.Errorf("unsupported tilde path %q; use '~/...' or an absolute path", p)
    }
    return nil
}

expanded, err := utils.ExpandHomeDir(path)
if err != nil {
    // fall back to the raw path or ask the user for an absolute path
    return fmt.Errorf("path %q: %w", path, err)
}

When it happens

Trigger: ExpandHomeDir(path) is called with a path where path[0] == '~' but path[1] is neither '/' nor '\\' and the path is longer than 1 character — e.g. '~otheruser/config.yml', '~foo', or a config value like '~home/file'.

Common situations: Config files specifying '~user/...' style paths (supported by shells but not by this helper); typos like '~config' instead of '~/config'; paths copied from examples using ~username expansion.

Related errors

• cannot expand user-specific home dir
• cannot find user-specific home dir
• command shell not defined in $SHELL environment variable
• client was not initialized
• github client v3 failed to load

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