chenhg5/cc-connect · error

resolve home directory: %w

Error message

resolve home directory: %w

What it means

codexAuthPath builds the path to the Codex auth.json file: it uses $CODEX_HOME if set, otherwise $HOME/.codex via os.UserHomeDir(). This error wraps the os.UserHomeDir failure, which on Linux/Unix means HOME is unset or empty (and no CODEX_HOME override exists), so the library cannot determine where auth.json lives.

Source

Thrown at agent/codex/usage.go:190

	}
	if bucket.SecondaryWindow != nil {
		windows = append(windows, core.UsageWindow{
			Name:              "Secondary",
			UsedPercent:       bucket.SecondaryWindow.UsedPercent,
			WindowSeconds:     bucket.SecondaryWindow.LimitWindowSeconds,
			ResetAfterSeconds: bucket.SecondaryWindow.ResetAfterSeconds,
			ResetAtUnix:       bucket.SecondaryWindow.ResetAt,
		})
	}
	return windows
}

func codexAuthPath() (string, error) {
	codexHome := os.Getenv("CODEX_HOME")
	if codexHome == "" {
		home, err := os.UserHomeDir()
		if err != nil {
			return "", fmt.Errorf("resolve home directory: %w", err)
		}
		codexHome = filepath.Join(home, ".codex")
	}
	return filepath.Join(codexHome, "auth.json"), nil
}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Set CODEX_HOME in the service/container environment to the directory containing auth.json
2. Set HOME for the daemon (systemd: Environment="HOME=/home/youruser" in the [Service] section)
3. Run the service as the user who owns the Codex credentials (User= in systemd unit)
4. Verify inside the same execution context: `tr '\0' '\n' < /proc/<pid>/environ | grep -E 'HOME|CODEX_HOME'`

Example fix

# before: systemd unit with empty env
[Service]
ExecStart=/usr/local/bin/cc-connect
# after
[Service]
User=youruser
Environment="HOME=/home/youruser"
ExecStart=/usr/local/bin/cc-connect

if os.Getenv("CODEX_HOME") == "" && os.Getenv("HOME") == "" {
    return errors.New("neither CODEX_HOME nor HOME is set; cannot locate codex auth.json")
}

_, err := agent.GetUsage(ctx)
if err != nil && strings.Contains(err.Error(), "resolve home directory") {
    return fmt.Errorf("set CODEX_HOME or HOME for the cc-connect process: %w", err)
}

When it happens

Trigger: CODEX_HOME is unset AND os.UserHomeDir() returns an error inside codexAuthPath, called from readOAuthTokens — typically when the process runs with a cleared environment (systemd unit without Environment=HOME, cron, container with minimal env, or `sudo -i` edge cases).

Common situations: Daemonizing cc-connect via systemd/launchd with a sanitized environment lacking HOME; Docker containers running as non-root without HOME set; CI runners with stripped env; invoking the binary through wrappers that clear the 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

• resolve home directory for Agy permission bridge: %w
• read %s: %w
• parse auth.json: %w
• auth.json missing tokens.access_token
• auth.json missing tokens.account_id

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