lima-vm/lima · error

failed to inspect instance %#q: %w

Error message

failed to inspect instance %#q: %w

What it means

Thrown by `limactl unprotect` when `store.Inspect` cannot load the named instance from the Lima instance store (`~/.lima/<instance>`). It wraps the underlying error (missing instance directory, corrupt instance.yml, etc.) with the instance name using Go's %#q quoting. The command aggregates these per-instance errors via errors.Join, so other instances in the same invocation are still processed.

Source

Thrown at cmd/limactl/unprotect.go:34

func newUnprotectCommand() *cobra.Command {
	unprotectCommand := &cobra.Command{
		Use:               "unprotect INSTANCE [INSTANCE, ...]",
		Short:             "Unprotect an instance",
		Args:              WrapArgsError(cobra.MinimumNArgs(1)),
		RunE:              unprotectAction,
		ValidArgsFunction: unprotectBashComplete,
		GroupID:           advancedCommand,
	}
	return unprotectCommand
}

func unprotectAction(cmd *cobra.Command, args []string) error {
	ctx := cmd.Context()
	var errs []error
	for _, instName := range args {
		inst, err := store.Inspect(ctx, instName)
		if err != nil {
			errs = append(errs, fmt.Errorf("failed to inspect instance %#q: %w", instName, err))
			continue
		}
		if !inst.Protected {
			logrus.Warnf("Instance %#q isn't protected. Skipping.", instName)
			continue
		}
		if err := inst.Unprotect(); err != nil {
			errs = append(errs, fmt.Errorf("failed to unprotect instance %#q: %w", instName, err))
			continue
		}
		logrus.Infof("Unprotected %#q", instName)
	}
	return errors.Join(errs...)
}

func unprotectBashComplete(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
	return bashCompleteInstanceNames(cmd)
}

View on GitHub (pinned to dd909d0973)

Solutions

1. Run `limactl list` to verify the exact instance name and correct the typo.
2. Check LIMA_HOME points to the directory that actually holds the instance (default ~/.lima).
3. Verify the instance directory exists and instance.yml is readable by the current user.
4. Recreate the instance if its metadata is corrupt.

Example fix

// before
limactl unprotect my-inst
// failed to inspect instance "my-inst": ...
// after
limactl list           # find correct name, e.g. my-inst-0
limactl unprotect my-inst-0

instNames, err := store.InstanceNames(ctx) // or limactl list
for _, want := range args {
    if !slices.Contains(instNames, want) {
        return fmt.Errorf("instance %q does not exist", want)
    }
}

if err := unprotectCmd.RunE(cmd, args); err != nil {
    // errors.Join result: inspect each joined error with errors.Is/As
    for _, e := range errors.Unwrap Multi(err) { ... }
}

When it happens

Trigger: Running `limactl unprotect NAME` where NAME does not exist in LIMA_HOME, the instance directory lacks a loadable instance.yml, or store.Inspect fails for another reason (e.g. permission problems on ~/.lima).

Common situations: Typo in the instance name; running as a different user whose LIMA_HOME does not contain the instance; instance was deleted while the CLI invocation was in flight; corrupted or partially written instance metadata after an interrupted operation.

Related errors

• cannot use `--sync` when the instance has host mounts config
• cannot use `--sync` with a wsl2 instance, the host directory
• failed to determine the host directory to sync: %w
• rsync is required for `--sync` but not found: %w
• expected the depth of the host working directory (%#q) to be

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