abiosoft/colima · critical

error retrieving home directory: %w

Error message

error retrieving home directory: %w

What it means

HomeDir (util/util.go:20) wraps os.UserHomeDir and calls logrus.Fatal on failure, so this is not a returned error — the process prints the message and exits immediately. On Unix, os.UserHomeDir reads only the $HOME environment variable, so it fails exactly when $HOME is unset or empty. colima resolves nearly everything (~ paths, config dirs) through HomeDir, so any entry point can trigger the exit.

Source

Thrown at util/util.go:20

import (
	"fmt"
	"net"
	"os"
	"os/exec"
	"path/filepath"
	"strings"

	"github.com/google/shlex"
	"github.com/sirupsen/logrus"
)

// HomeDir returns the user home directory.
func HomeDir() string {
	home, err := os.UserHomeDir()
	if err != nil {
		// this should never happen
		logrus.Fatal(fmt.Errorf("error retrieving home directory: %w", err))
	}
	return home
}

// RandomAvailablePort returns an available port on the host machine.
func RandomAvailablePort() int {
	listener, err := net.Listen("tcp", ":0")
	if err != nil {
		logrus.Fatal(fmt.Errorf("error picking an available port: %w", err))
	}

	if err := listener.Close(); err != nil {
		logrus.Fatal(fmt.Errorf("error closing temporary port listener: %w", err))
	}

	return listener.Addr().(*net.TCPAddr).Port
}

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Set HOME before invoking colima: `HOME=/Users/me colima start`
2. For services (systemd/launchd), add Environment="HOME=/Users/me" or an EnvironmentFile with HOME
3. In containers, set a valid USER/HOME or export HOME=/root
4. Prefer invoking colima from a login shell when possible

Example fix

# before (cron/systemd: HOME unset -> colima exits immediately)
exec colima start

# after
Environment="HOME=/Users/me"
ExecStart=/opt/homebrew/bin/colima start

// fail with a clear message before colima's logrus.Fatal does
if os.Getenv("HOME") == "" {
    log.Fatal("HOME is unset — set it (export HOME=/Users/me) before running colima")
}

// no catch possible: logrus.Fatal exits the process.
// Only defense is ensuring HOME is set in every invocation context
// (cron lines, systemd units, Docker ENV, launchd plists).

When it happens

Trigger: Running colima with a sanitized environment: `env -i colima ...`, cron/systemd/launchd jobs that don't inherit HOME, minimal containers, or `HOME= colima start`.

Common situations: Automation in CI images that strip env; Docker containers without USER/HOME set; sudo -i edge cases where HOME points at a missing dir; scripts that unset variables before invoking colima.

Related errors

• cannot fetch required directory: %w
• error editing config file: %w
• error editing template file: %w
• no editor found in $PATH, kindly set $EDITOR environment var
• cannot make required directory: %w

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