abiosoft/colima · critical

cannot fetch required directory: %w

Error message

cannot fetch required directory: %w

What it means

configDir values in config/files.go are requiredDir structs whose Dir() method calls logrus.Fatal when the underlying dir() function errors. The wrapped error comes from environment lookups such as os.UserHomeDir (fails when $HOME is unset), os.UserConfigDir, or os.UserCacheDir. This is a fatal crash that exits the process; it is not returned as an error value to callers.

Source

Thrown at config/files.go:36

	// dir is a func to enable deferring the value of the directory
	// until execution time.
	// if dir() returns an error, a fatal error is triggered.
	dir func() (string, error)

	computedDir *string
}

// Dir returns the directory path.
// It ensures the directory is created on the filesystem by calling
// `mkdir` prior to returning the directory path.
func (r *requiredDir) Dir() string {
	if r.computedDir != nil {
		return *r.computedDir
	}

	dir, err := r.dir()
	if err != nil {
		logrus.Fatal(fmt.Errorf("cannot fetch required directory: %w", err))
	}

	r.once.Do(func() {
		if err := fsutil.MkdirAll(dir, 0755); err != nil {
			logrus.Fatal(fmt.Errorf("cannot make required directory: %w", err))
		}
	})

	r.computedDir = &dir
	return dir
}

var (
	configBaseDir = requiredDir{
		dir: func() (string, error) {
			// colima home explicit config
			dir := os.Getenv("COLIMA_HOME")
			if _, err := os.Stat(dir); err == nil {

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Export a valid HOME before running colima: export HOME=/root (or the invoking user's home)
2. Set COLIMA_HOME to a writable absolute path to bypass home-dir resolution
3. For cache dir failures, set COLIMA_CACHE_HOME or XDG_CACHE_HOME to a writable location
4. Fix the service unit or wrapper script to pass HOME and PATH through to the process

Example fix

# before
docker run --rm colima-image colima version   # fatal: cannot fetch required directory

# after
docker run --rm -e HOME=/root colima-image colima version

// logrus.Fatal exits the process; validate the environment BEFORE any
// call that resolves a config/cache/lima directory.
if os.Getenv("HOME") == "" && os.Getenv("COLIMA_HOME") == "" {
    return fmt.Errorf("HOME or COLIMA_HOME must be set before running colima")
}
if _, err := os.UserHomeDir(); err != nil {
    return fmt.Errorf("cannot resolve home directory: %w", err)
}

// Not catchable: requiredDir.Dir() calls logrus.Fatal and exits.
// The only defense is pre-checking HOME/COLIMA_HOME/XDG_* variables
// before invoking any colima package that resolves directories.

When it happens

Trigger: Invoking any colima command that resolves a config path (essentially all of them) in an environment where $HOME is unset or empty so os.UserHomeDir() returns an error: headless containers, minimal CI images, or launchd/systemd/cron units running with a scrubbed environment.

Common situations: Running colima inside Docker or CI containers without HOME; brew services or scheduled jobs with sanitized env; scripts using env -i; a COLIMA_HOME pointing into an inaccessible mount producing stat failures during resolution.

Related errors

• cannot make required directory: %w
• error retrieving home directory: %w
• error persisting runtime settings: %w
• error persisting kubernetes settings: %w
• error deleting configs: %w

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