lima-vm/lima · error

instance %#q is stopped, run `limactl start %s` to start the

Error message

instance %#q is stopped, run `limactl start %s` to start the instance

What it means

limactl guest-install refuses to operate on an instance whose recorded status is 'Stopped'. The instance directory exists, but there is no running VM to install guest files into, so the command aborts with a hint to start the instance first. This is a pre-flight state check in guestInstallAction right after inspecting the instance from the store.

Source

Thrown at cmd/limactl/guest-install.go:68

	if err != nil {
		return "", err
	}
	out = bytes.TrimSuffix(out, []byte{'\n'})
	return string(out), nil
}

func guestInstallAction(cmd *cobra.Command, args []string) error {
	instName := DefaultInstanceName
	if len(args) > 0 {
		instName = args[0]
	}

	inst, err := store.Inspect(cmd.Context(), instName)
	if err != nil {
		return err
	}
	if inst.Status == limatype.StatusStopped {
		return fmt.Errorf("instance %#q is stopped, run `limactl start %s` to start the instance", instName, instName)
	}

	ctx := cmd.Context()

	sshExe := "ssh"
	sshConfig := filepath.Join(inst.Dir, filenames.SSHConfig)
	sshFlags := []string{"-F", sshConfig}

	scpExe := "scp"
	scpFlags := sshFlags

	hostname := fmt.Sprintf("lima-%s", inst.Name)
	prefix := *inst.Config.GuestInstallPrefix

	// lima-guestagent
	guestAgentBinary, err := usrlocal.GuestAgentBinary(*inst.Config.OS, *inst.Config.Arch)
	if err != nil {
		return err

View on GitHub (pinned to dd909d0973)

Solutions

1. Run `limactl start <instance>` first, then retry guest-install
2. Verify the intended instance name with `limactl list` — you may be targeting the wrong (stopped) instance
3. If the instance is broken, delete and recreate it with `limactl delete <instance>` then `limactl create/start`

Example fix

// before
limactl guest-install myinstance /path/script.sh
// after
limactl start myinstance && limactl guest-install myinstance /path/script.sh

inst, err := store.Inspect(ctx, instName)
if err != nil { return err }
if inst.Status == limatype.StatusStopped {
    return fmt.Errorf("start instance first: limactl start %s", instName)
}

func isRunning(inst *limatype.Instance) bool { return inst != nil && inst.Status != limatype.StatusStopped }

if err := startInstance(ctx, instName); err != nil {
    if strings.Contains(err.Error(), "is stopped") { /* recover by starting */ }
    return err
}

When it happens

Trigger: Running `limactl guest-install <name> ...` when store.Inspect returns an Instance with Status == limatype.StatusStopped, i.e. the instance was created or previously shut down and never started.

Common situations: Scripting guest-install after `limactl create` without a `limactl start`; an instance crashed or was stopped by `limactl stop`; running guest-install in CI where the VM was torn down between steps.

Related errors

• invalid value for static parameter: %#q
• invalid parameter %#q, expected `static=` followed by a bool
• invalid parameter %#q, expected NAME=VALUE
• template does not define param %#q
• invalid value for number of cpus, must be >= 0

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