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 tunnel` requires the target instance to be running; if `store.Inspect` reports StatusStopped, the command refuses and suggests `limactl start <inst>`. Tunneling needs the guest's SSH endpoint, which only exists while the VM is up.

Source

Thrown at cmd/limactl/tunnel.go:77

	}
	port, err := flags.GetInt("socks-port")
	if err != nil {
		return err
	}
	if port != 0 && (port < 1024 || port > 65535) {
		return fmt.Errorf("invalid socks port %d", port)
	}
	stdout, stderr := cmd.OutOrStdout(), cmd.ErrOrStderr()
	instName := args[0]
	inst, err := store.Inspect(ctx, instName)
	if err != nil {
		if errors.Is(err, os.ErrNotExist) {
			return fmt.Errorf("instance %#q does not exist, run `limactl create %s` to create a new instance", instName, instName)
		}
		return err
	}
	if inst.Status == limatype.StatusStopped {
		return fmt.Errorf("instance %#q is stopped, run `limactl start %s` to start the instance", instName, instName)
	}

	if port == 0 {
		port, err = freeport.TCP()
		if err != nil {
			return err
		}
	}

	sshExe, err := sshutil.NewSSHExe()
	if err != nil {
		return err
	}

	sshOpts, err := sshutil.SSHOpts(
		ctx,
		sshExe,
		inst.Dir,

View on GitHub (pinned to dd909d0973)

Solutions

Run `limactl start <inst>` and retry the tunnel command
Check status with `limactl list` to confirm the instance is Running
If start reports it is already running or stale, try `limactl stop -f <inst>` then start again
Ensure no leftover VM processes; restart the instance to clear stale stopped state

Example fix

// before
limactl tunnel myinst
// error: instance "myinst" is stopped
// after
limactl start myinst
limactl tunnel myinst

Defensive patterns

Strategy: validation

Validate before calling

out, err := exec.Command("limactl", "list").Output()
if err != nil { return err }
for _, line := range strings.Split(string(out), "\n") {
	f := strings.Fields(line)
	if len(f) >= 2 && f[0] == instName {
		if f[1] != "Running" {
			return fmt.Errorf("instance %q is %s; run `limactl start %s`", instName, f[1], instName)
		}
	}
}

Try / catch

if inst.Status == limatype.StatusStopped {
	return fmt.Errorf("instance %q is stopped, run `limactl start %s` first", instName, instName)
}

Prevention

Check `limactl list` status is Running before tunneling
Always start the VM after host reboot before tunnel commands
Handle stale status by stop -f + start if the VM process died unexpectedly

When it happens

Trigger: Running `limactl tunnel <name>` while the instance's status file records StatusStopped — after `limactl stop`, after a crashed/unsaved VM, or when the status is stale because the VM process died.

Common situations: Forgetting to start the VM after rebooting the host; tunnel command left in shell history executed post-stop; stale status after abnormal host shutdown (may need `limactl start` to recover).

Related errors

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