abiosoft/colima · error

error retrieving home directory on host

Error message

error retrieving home directory on host

What it means

Raised in the kubeconfig setup chain when the host's HOME environment variable is empty (c.host.Env("HOME") == ""). Colima needs the host home directory to locate/create ~/.kube and place the merged k3s kubeconfig there; without HOME there is no target path, so setup aborts before any host command is run.

Source

Thrown at environment/container/kubernetes/kubeconfig.go:35

func (c kubernetesRuntime) provisionKubeconfig(ctx context.Context) error {
	ip := limautil.IPAddress(config.CurrentProfile().ID)
	if ip == c.guest.Get(masterAddressKey) {
		return nil
	}

	log := c.Logger(ctx)
	a := c.Init(ctx)

	a.Stage("updating config")

	// remove existing configs (if any)
	// this is safe as the profile name is unique to colima
	c.unsetKubeconfig(a)

	// ensure host kube directory exists
	hostHome := c.host.Env("HOME")
	if hostHome == "" {
		return fmt.Errorf("error retrieving home directory on host")
	}

	profile := config.CurrentProfile().ID
	hostKubeDir := filepath.Join(hostHome, ".kube")
	a.Add(func() error {
		return c.host.Run("mkdir", "-p", filepath.Join(hostKubeDir, "."+profile))
	})

	kubeconfFile := filepath.Join(hostKubeDir, "config")
	envKubeConfFile := c.host.Env("KUBECONFIG")
	if envKubeConfFile != "" {
		kubeconfFile = filepath.SplitList(envKubeConfFile)[0]
	}
	tmpkubeconfFile := filepath.Join(hostKubeDir, "."+profile, "colima-temp")

	// manipulate in VM and save to host
	a.Add(func() error {
		kubeconfig, err := c.guest.Read("/etc/rancher/k3s/k3s.yaml")

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Run colima from a normal login shell where HOME is set: 'HOME=$HOME colima start --kubernetes'.
2. For scripts/services, explicitly export HOME before invoking colima (e.g. in the systemd unit: Environment=HOME=/Users/me or EnvironmentFile covering HOME).
3. If you must run as root, use 'sudo -E colima ...' (preserve env) or set HOME explicitly, and understand kubeconfig will then target that HOME's ~/.kube.
4. Verify with 'echo $HOME' and 'env | grep HOME' in the exact context that fails before re-running.

Example fix

# before
$ sudo -i some-wrapper.sh   # HOME cleared/changed
# after
$ sudo -E env HOME="$HOME" ./some-wrapper.sh   # colima sees the real home

// guard before calling any kubeconfig setup
if os.Getenv("HOME") == "" {
    return fmt.Errorf("HOME is not set; set HOME=<your home> and retry")
}

func hasHomeEnv() bool { return os.Getenv("HOME") != "" }

hostHome := c.host.Env("HOME")
if hostHome == "" {
    // fallback: expand ~ via os.UserHomeDir() before giving up
    if h, err := os.UserHomeDir(); err == nil {
        hostHome = h
    } else {
        return fmt.Errorf("error retrieving home directory on host: %w", err)
    }
}

When it happens

Trigger: Any invocation of 'colima start --kubernetes' (or kube context update) in an environment where HOME is unset: cron jobs, launchd/systemd units, bare 'sudo -E' misuse stripping env, some CI runners, or 'env -i colima ...'. On the Go side, os.Getenv("HOME") returns "" when the variable is absent (notably sudo sets HOME to root's home only with -H/-i, and unset when the caller clears it).

Common situations: Running colima from a launchd agent or Docker/CI container without a login shell; scripts that use 'sudo env -i' or sanitize the environment; switched users via 'su' without '-' so HOME points nowhere; shell misconfiguration exporting HOME=''.

Related errors

• error backing up kubeconfig: %w
• error updating kubeconfig: %w
• error fetching kubeconfig on guest: %w
• error persisting kubernetes settings: %w
• dependency check failed for %s: %w

AI-assisted analysis of abiosoft/colima@c3a5f9184d (2026-08-15). Data as JSON: /api/errors/d93a6ea4951c29c5. Report an issue: GitHub.