chenhg5/cc-connect · error

pi: cannot determine settings path

Error message

pi: cannot determine settings path

What it means

readSettings resolves pi's settings.json path via settingsPath(), which joins pi's settings dir (derived from HOME / PI_USER_DIR) with settings.json. If the settings directory cannot be determined (empty path), the adapter returns this error instead of attempting a read. It is thrown by readSettings, which backs readSettingsModels and readDefaultModel.

Source

Thrown at agent/pi/pi.go:429

	dir := piSettingsDir()
	if dir == "" {
		return ""
	}
	return filepath.Join(dir, "settings.json")
}

// piSettings represents the structure of pi's settings.json relevant fields.
type piSettings struct {
	EnabledModels  []string `json:"enabledModels"`
	DefaultModel   string   `json:"defaultModel"`
	DefaultProvider string  `json:"defaultProvider"`
}

// readSettings reads and parses pi's settings.json.
func readSettings() (*piSettings, error) {
	path := settingsPath()
	if path == "" {
		return nil, fmt.Errorf("pi: cannot determine settings path")
	}
	data, err := os.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("pi: read settings: %w", err)
	}
	var s piSettings
	if err := json.Unmarshal(data, &s); err != nil {
		return nil, fmt.Errorf("pi: parse settings: %w", err)
	}
	return &s, nil
}

// readSettingsModels returns the enabledModels from settings.json as ModelOptions.
func readSettingsModels() ([]core.ModelOption, error) {
	s, err := readSettings()
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Set the HOME environment variable for the process running cc-connect to the user's home directory.
2. Point the adapter at pi's data explicitly via PI_USER_DIR if supported, so the settings dir is not derived from HOME.
3. If running under systemd, add Environment=HOME=/home/<user> (or EnvironmentFile) to the unit; under docker pass -e HOME=...
4. Create ~/.pi/agent/settings.json if pi was never run, though path resolution failing is an env problem, not a missing-file problem.

Example fix

// systemd unit, before
[Service]
ExecStart=/usr/local/bin/cc-connect
// after
[Service]
Environment=HOME=/home/alice
ExecStart=/usr/local/bin/cc-connect

if os.Getenv("HOME") == "" && os.Getenv("PI_USER_DIR") == "" {
    return fmt.Errorf("cannot read pi settings: HOME/PI_USER_DIR unset in this environment")
}
// proceed with readSettingsModels()/readDefaultModel()

models, err := readSettingsModels()
if err != nil && strings.Contains(err.Error(), "cannot determine settings path") {
    return fmt.Errorf("pi settings unavailable: set HOME or PI_USER_DIR for the service user: %w", err)
}

When it happens

Trigger: Calling any API that reads pi settings (model listing, default model lookup) when piSettingsDir() returns "" — typically when the HOME environment variable is unset/empty and PI_USER_DIR is not set, so the adapter cannot compute ~/.pi/agent.

Common situations: Running the daemon under systemd/launchd/docker with a scrubbed environment (no HOME); running as a system service user without a home directory; CI containers that don't set HOME for the service account.

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
• resolve home directory: %w
• gemini: cannot determine home dir: %w
• pi: read settings: %w
• pi: parse settings: %w

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