What causes "cannot resolve home directory: %w" in chenhg5/cc-connect?

Set the HOME environment variable for the process (e.g. Environment=HOME=/home/user in the systemd unit)

cannot resolve home directory

Error message

cannot resolve home directory: %w

What it means

resolveLocalDirPath wraps os.UserHomeDir failures with this error when the target path starts with '~' or '~/'. The home directory cannot be determined because the environment provides no usable HOME (or equivalent) value, so the tilde path cannot be expanded.

Solutions

Set the HOME environment variable for the process (e.g. Environment=HOME=/home/user in the systemd unit)
Replace the ~/ prefix in the configured path with an absolute path
Run the service as a normal login user so the home directory resolves
Use the daemon's baseDir-relative path instead of a tilde path

Example fix

// before (config.toml)
workspaceDir = "~/projects/repo"
// after
workspaceDir = "/home/alice/projects/repo"

Defensive patterns

Strategy: validation

Validate before calling

if os.Getenv("HOME") == "" {
    return fmt.Errorf("HOME is not set; tilde paths cannot be resolved")
}

Try / catch

path, err := resolveLocalDirPath(target, baseDir)
if err != nil && strings.Contains(err.Error(), "cannot resolve home directory") {
    slog.Warn("HOME unset; expand tilde manually or use absolute path", "err", err)
    return err
}

Prevention

Always set HOME in service units (systemd: Environment=HOME=%h)
Prefer absolute paths over ~/ in daemon configs
Validate config paths resolve at startup, not at first use
Run daemons as a normal user with a defined home directory

When it happens

Trigger: Calling resolveLocalDirPath with target == "~" or a "~/..." path while os.UserHomeDir() returns an error — typically because $HOME is unset/empty (Linux) or the user profile cannot be resolved (Windows).

Common situations: Running the daemon under systemd with a minimal environment lacking HOME; running in a container or cron job where HOME is not set; SSH non-login shells with stripped environment.

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

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/0639695bc9092a0c. Report an issue: GitHub.

Appendix: source

Thrown at core/engine.go:16979

	return false
}

func looksLikeGitURL(s string) bool {
	return strings.HasPrefix(s, "https://") ||
		strings.HasPrefix(s, "http://") ||
		strings.HasPrefix(s, "git@") ||
		strings.HasPrefix(s, "ssh://")
}

// resolveLocalDirPath resolves a user-provided directory path to an absolute
// path, expanding ~/... and joining relative paths with baseDir. It rejects
// paths that escape baseDir via ../ traversal.
func resolveLocalDirPath(target, baseDir string) (string, error) {
	dirPath := target
	if dirPath == "~" || strings.HasPrefix(dirPath, "~/") {
		home, err := os.UserHomeDir()
		if err != nil {
			return "", fmt.Errorf("cannot resolve home directory: %w", err)
		}
		dirPath = filepath.Join(home, dirPath[2:])
	} else if !filepath.IsAbs(dirPath) {
		dirPath = filepath.Join(baseDir, dirPath)
	}
	cleaned := filepath.Clean(dirPath)
	resolved, err := filepath.EvalSymlinks(cleaned)
	if err != nil {
		resolved = cleaned
	}
	if baseDir != "" && !filepath.IsAbs(target) && !strings.HasPrefix(target, "~") {
		cleanBase := filepath.Clean(baseDir)
		if evalBase, err := filepath.EvalSymlinks(cleanBase); err == nil {
			cleanBase = evalBase
		}
		if !strings.HasPrefix(resolved, cleanBase+string(filepath.Separator)) && resolved != cleanBase {
			return "", fmt.Errorf("path escapes workspace base directory")
		}

View on GitHub (pinned to 4000b2338a)