lima-vm/lima · warning

failed to read driver directory %#q: %w

Error message

failed to read driver directory %#q: %w

What it means

discoverDriversInDir enumerates executable `lima-driver-*` files in a driver directory (standard libexec dirs or paths from LIMA_DRIVERS). This error wraps an os.ReadDir failure, meaning the directory itself could not be read — it doesn't exist, has wrong permissions, or an I/O error occurred. The caller (discoverDrivers) logs it as a warning and continues, so external drivers from that directory are simply unavailable.

Source

Thrown at pkg/registry/registry.go:141

	if err != nil {
		return err
	}

	logrus.Debugf("Discovering external drivers in %v", stdDriverDirs)
	for _, dir := range stdDriverDirs {
		if _, err := os.Stat(dir); err == nil {
			if err := discoverDriversInDir(dir); err != nil {
				logrus.Warnf("Error discovering external drivers in %#q: %v", dir, err)
			}
		}
	}
	return nil
}

func discoverDriversInDir(dir string) error {
	entries, err := os.ReadDir(dir)
	if err != nil {
		return fmt.Errorf("failed to read driver directory %#q: %w", dir, err)
	}

	for _, entry := range entries {
		if entry.IsDir() {
			continue
		}

		info, err := entry.Info()
		if err != nil {
			logrus.Warnf("Failed to get info for %#q: %v", entry.Name(), err)
			continue
		}

		if !isExecutable(info.Mode()) {
			continue
		}

		driverPath := filepath.Join(dir, entry.Name())

View on GitHub (pinned to dd909d0973)

Solutions

1. Check the directory exists and is readable: `ls -la <dir>` (the dir path is quoted in the error message); fix the path or permissions with `chmod o+rx <dir>`.
2. If LIMA_DRIVERS points at the bad directory, correct or unset the variable so only the standard driver dirs are scanned.
3. Reinstall the external driver package (or create the directory) so the expected `lima-driver-*` location exists.

Example fix

// before
export LIMA_DRIVERS=/usr/local/lib/lima-drivers  # directory missing
// after
export LIMA_DRIVERS=$HOME/.local/libexec/lima     # existing, readable directory
# or: sudo chmod a+rx /usr/local/libexec/lima

// Before relying on external drivers, ensure each directory in LIMA_DRIVERS exists and is readable:
// for d in $(IFS=:; echo $LIMA_DRIVERS); do [ -d "$d" ] && [ -r "$d" ] && [ -x "$d" ] || echo "unusable driver dir: $d"; done
// Also verify standard dirs: [ -d "$(brew --prefix)/libexec/lima" ] 2>/dev/null || true

// discovery failures are logged-and-skipped by Lima; to detect them yourself:
if err := discoverDriversInDir(dir); err != nil {
	var perr *fs.PathError
	if errors.As(err, &perr) && errors.Is(perr.Err, fs.ErrPermission) {
		log.Warnf("driver dir %s not readable: %v; fix with chmod o+rx", dir, err)
	}
}

When it happens

Trigger: os.ReadDir(dir) fails inside discoverDriversInDir: the LIMA_DRIVERS path entry or the standard libexec/lima driver directory does not exist (ENOENT), is not readable by the current user (EACCES/EPERM), or a filesystem error occurs while listing it.

Common situations: LIMA_DRIVERS set to a directory that was deleted or misspelled; installing external drivers into a root-only-readable directory and running limactl as a non-root user; an NFS/permission issue on the libexec directory after a partial uninstall or package upgrade.

Related errors

• failed to unprotect instance %#q: %w
• open disk: %w
• failed to remove the autostart entry for instance %#q: %w
• failed to remove stale raw image %q: %w
• failed to remove stale raw digest file %q: %w

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/aca4f61457eddf84. Report an issue: GitHub.