chenhg5/cc-connect · error

codex: resolve codex home: %w

Error message

codex: resolve codex home: %w

What it means

ensureCodexProviderConfig writes provider settings into $CODEX_HOME/config.toml. It first resolves the codex home via resolveCodexHomeForConfig (explicit codexHome arg, else CODEX_HOME/user home). If that resolution fails, the error is wrapped with this prefix. Without a home directory the provider config cannot be located or created.

Source

Thrown at agent/codex/provider_config.go:21

import (
	"encoding/json"
	"fmt"
	"log/slog"
	"os"
	"path/filepath"
	"strings"
)

// ensureCodexProviderConfig writes or updates a [model_providers.<name>] section
// in $CODEX_HOME/config.toml so that Codex CLI can use the provider's wire_api
// and http_headers settings.
func ensureCodexProviderConfig(codexHome, name, baseURL, wireAPI string, headers map[string]string) error {
	if name == "" {
		return nil
	}
	home, err := resolveCodexHomeForConfig(codexHome)
	if err != nil {
		return fmt.Errorf("codex: resolve codex home: %w", err)
	}
	if err := os.MkdirAll(home, 0o755); err != nil {
		return fmt.Errorf("codex: mkdir codex home: %w", err)
	}

	cfgPath := filepath.Join(home, "config.toml")
	raw, _ := os.ReadFile(cfgPath)
	content := string(raw)

	section := buildProviderSection(name, baseURL, wireAPI, headers)
	updated := upsertProviderSection(content, name, section)

	if err := os.WriteFile(cfgPath, []byte(updated), 0o644); err != nil {
		return fmt.Errorf("codex: write config.toml: %w", err)
	}
	slog.Debug("codex: wrote provider config", "provider", name, "path", cfgPath)
	return nil
}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Set CODEX_HOME to an absolute writable path in the environment.
2. Set HOME (or ensure the Windows user profile loads) so os.UserHomeDir succeeds.
3. Pass an explicit codexHome via agent options so resolution never depends on the environment.
4. Check the wrapped inner error (%w) for the precise UserHomeDir failure reason.

Example fix

// before
ExecStart=/usr/local/bin/cc-connect  # HOME unset
// after
[Service]
Environment=HOME=/home/alice
Environment=CODEX_HOME=/home/alice/.codex

if os.Getenv("CODEX_HOME") == "" {
    if _, err := os.UserHomeDir(); err != nil {
        return fmt.Errorf("set CODEX_HOME before starting codex with a provider: %w", err)
    }
}

if err := ensureCodexProviderConfig(home, name, baseURL, wireAPI, headers); err != nil {
    return fmt.Errorf("provider setup failed; is CODEX_HOME/HOME set? %w", err)
}

When it happens

Trigger: StartSession with a configured provider name while resolveCodexHomeForConfig fails — i.e. no explicit codexHome in agent opts, CODEX_HOME unset, and os.UserHomeDir() errors (HOME missing).

Common situations: Daemon/service environments without HOME; containers running as a non-login user; misconfigured unit files that scrub the environment; Windows services without a user profile loaded.

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: %w
• provider %q not found in project %q
• global provider %q not found
• cron project not found
• attachment send is disabled by config

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