abiosoft/colima · critical

cannot make required directory: %w

Error message

cannot make required directory: %w

What it means

requiredDir.Dir() creates the resolved directory with fsutil.MkdirAll(dir, 0755) inside a sync.Once; any failure calls logrus.Fatal and the process exits. Typical causes are permission denied on a parent directory, a path component existing as a regular file, a read-only filesystem, or ENOSPC. Like error 93, this cannot be caught by callers.

Source

Thrown at config/files.go:41

	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 {
				return dir, nil
			}

			// user home directory
			homeDir, err := os.UserHomeDir()

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Inspect the path in the error with ls -ld on the dir and its parents; if a component is a regular file, remove or rename it
2. Fix ownership and permissions: chown -R $(whoami) on the directory or chmod u+w on the parent
3. Point COLIMA_HOME (and COLIMA_CACHE_HOME) at a writable location with free space
4. Free disk space or move the config root off the full volume

Example fix

# before: ~/.colima is a regular file
ls -l ~/.colima    # -rw-r--r--
colima start       # fatal: cannot make required directory

# after
rm ~/.colima && colima start

// Probe writability before triggering the fatal MkdirAll path.
if fi, err := os.Stat(dir); err == nil && !fi.IsDir() {
    return fmt.Errorf("%s exists as a file, remove it first", dir)
}
if err := os.MkdirAll(dir, 0755); err != nil {
    return fmt.Errorf("cannot create %s: %w (check permissions and disk space)", dir, err)
}

// Not catchable: MkdirAll failure goes through logrus.Fatal and exits.
// Pre-flight the directory: stat for file/dir conflicts, verify parent
// permissions, and confirm free disk space before running colima.

When it happens

Trigger: Any colima command where directory resolution succeeds but mkdir fails: ~/.colima existing as a plain file instead of a directory, COLIMA_HOME/LIMA_HOME pointing under a read-only volume, a parent directory owned by root after sudo misuse, or the disk being full.

Common situations: Accidentally creating ~/.colima as a file (e.g. touch ~/.colima); first run on a read-only NFS home; permissions broken by recursive chown or home migration; disk exhaustion during initial provisioning.

Related errors

• error persisting runtime settings: %w
• error persisting kubernetes settings: %w
• error deleting configs: %w
• error reading ssh config: %w
• error modifying %s: %w

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