lima-vm/lima · error

unable to load instance %s: %w

Error message

unable to load instance %s: %w

What it means

limactl list wraps any failure to load an instance's on-disk state (the per-instance directory under $LIMA_HOME containing lima.yaml, etc.) into this error. It is thrown by listAction in cmd/limactl/list.go:247 when store.LoadInstance (or similar) returns an error that is not a 'being cloned or deleted' transient condition — those are skipped with a warning instead. The %w wrapping preserves the underlying cause (file missing, YAML parse error, permission denied).

Source

Thrown at cmd/limactl/list.go:247

	}

	// get the state and config for all the requested instances
	var instances []*limatype.Instance
	for _, instanceName := range instanceNames {
		instance, err := store.Inspect(ctx, instanceName)
		if err != nil {
			if errors.Is(err, os.ErrNotExist) {
				if broken := brokenInstance(instanceName, err); broken != nil {
					instances = append(instances, broken)
					continue
				}
				logrus.Warnf("Skipping instance %#q: %v (being cloned or deleted?)", instanceName, err)
				if len(args) > 0 {
					unmatchedInstances = true
				}
				continue
			}
			return fmt.Errorf("unable to load instance %s: %w", instanceName, err)
		}
		instances = append(instances, instance)
	}

	if len(filter) > 0 {
		var filterExprs []string
		for _, f := range filter {
			filterExprs = append(filterExprs, "select("+f+")")
		}
		instances, err = filterInstances(ctx, instances, filterExprs)
		if err != nil {
			return err
		}
	}

	if quiet && len(yq) == 0 {
		for _, instance := range instances {
			fmt.Fprintln(cmd.OutOrStdout(), instance.Name)

View on GitHub (pinned to dd909d0973)

Solutions

1. Inspect the instance directory ($LIMA_HOME/lima/<name>/lima.yaml) and fix or restore the YAML
2. If the instance is dead, remove it: `limactl delete -f <name>` or manually delete the directory and re-list
3. Check file permissions on $LIMA_HOME subdirectories (should be readable by the current user)
4. Run `limactl list` without arguments to see which instances load and which warn/skip

Example fix

// before (broken instance dir)
$ limactl list myvm
Error: unable to load instance myvm: open .../lima.yaml: no such file or directory
// after
$ rm -rf ~/.lima/myvm   # or fix lima.yaml
$ limactl list

if [ ! -f "$LIMA_HOME/lima/$NAME/lima.yaml" ]; then echo "instance $NAME missing/broken"; exit 1; fi

func instanceLoadable(limaDir, name string) bool {
	info, err := os.Stat(filepath.Join(limaDir, "lima", name, "lima.yaml"))
	return err == nil && !info.IsDir()
}

instance, err := store.LoadInstance(ctx, instDir, name)
if err != nil {
	if errors.Is(err, os.ErrNotExist) { /* recreate or delete stale dir */ }
	return fmt.Errorf("unable to load instance %s: %w", name, err)
}

When it happens

Trigger: Running `limactl list <name>` (or with explicit instance args) where the instance directory exists but its lima.yaml is corrupt, unreadable, or the directory was partially deleted/created outside a state that the loader recognizes, and the load error is not the transient in-progress error.

Common situations: Interrupted `limactl create/delete/clone` leaving a half-written instance dir; manually editing or truncating lima.yaml; $LIMA_HOME on a mounted volume with permission issues; stale instance dirs after a Lima version upgrade changed the config format.

Related errors

• the YAML is invalid, attempted to save the buffer as %#q but
• failed to determine if another hostagent is running: %w
• failed to determine the host directory to sync: %w
• failed to unprotect instance %#q: %w
• pidfile %#q already exists

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