chenhg5/cc-connect · error

resolve home directory for Agy permission bridge: %w

Error message

resolve home directory for Agy permission bridge: %w

What it means

createAgyConfigOverlay resolves the current user's home directory (os.UserHomeDir) to locate the real ~/.gemini config root for the permission bridge overlay. If the home directory cannot be resolved, it returns this wrapped error and the bridge is not created.

Source

Thrown at agent/antigravity/permission_bridge.go:100

		ctx:       bridgeCtx,
		cancel:    cancel,
		listener:  listener,
		address:   listener.Addr().String(),
		token:     base64.RawURLEncoding.EncodeToString(tokenBytes),
		rootDir:   rootDir,
		configDir: configDir,
		events:    events,
		pending:   make(map[string]chan core.PermissionResult),
	}
	bridge.wg.Add(1)
	go bridge.acceptLoop()
	return bridge, nil
}

func createAgyConfigOverlay(rootDir string) (string, error) {
	homeDir, err := os.UserHomeDir()
	if err != nil {
		return "", fmt.Errorf("resolve home directory for Agy permission bridge: %w", err)
	}
	// Antigravity currently stores its CLI state under .gemini and exposes it
	// through the --gemini_dir compatibility flag.
	realConfigRoot := filepath.Join(homeDir, ".gemini")
	overlayConfigRoot := filepath.Join(rootDir, "agy-config")
	overlayConfigDir := filepath.Join(overlayConfigRoot, "config")
	if err := os.MkdirAll(overlayConfigDir, 0o700); err != nil {
		return "", fmt.Errorf("create Agy permission overlay: %w", err)
	}

	if err := mirrorDirectoryEntries(realConfigRoot, overlayConfigRoot, map[string]bool{"config": true}); err != nil {
		return "", err
	}
	realConfigDir := filepath.Join(realConfigRoot, "config")
	if err := mirrorDirectoryEntries(realConfigDir, overlayConfigDir, map[string]bool{"hooks.json": true}); err != nil {
		return "", err
	}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Set the HOME environment variable for the process (e.g. Environment=HOME=/home/user in the systemd unit).
2. Ensure the user the daemon runs as exists in /etc/passwd with a valid home directory.
3. If using systemd, add SetEnvironment=HOME=%h or run with a Login shell context.
4. Verify os.UserHomeDir works for the same user: `sudo -u <user> sh -c 'echo $HOME'`.

Example fix

// before: systemd unit without HOME
[Service]
ExecStart=/usr/local/bin/cc-connect
// after
[Service]
Environment=HOME=/home/ccuser
ExecStart=/usr/local/bin/cc-connect

// Go: check HOME is resolvable before starting the daemon
if os.Getenv("HOME") == "" && runtime.GOOS != "windows" {
    return errors.New("HOME is not set; antigravity bridge requires it")
}

if err := startAntigravitySession(); err != nil && strings.Contains(err.Error(), "resolve home directory") {
    // log hint: set HOME/USERPROFILE for the service user
}

When it happens

Trigger: newAgyPermissionBridge → createAgyConfigOverlay when os.UserHomeDir fails: HOME (and USERPROFILE on Windows) unset for the current user.

Common situations: Running cc-connect under systemd or a daemon with a scrubbed environment (no HOME), running as a setuid/service account without a home dir, or containers running as a UID with no passwd entry.

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 dir: %w
• listen for Agy permission hooks: %w
• generate permission bridge token: %w
• create Agy permission overlay: %w
• parse existing Agy hooks %s: %w

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