instance %#q does not exist, run `limactl create %s` to crea

Error message

instance %#q does not exist, run `limactl create %s` to create a new instance

What it means

`limactl tunnel` looks up the target instance with `store.Inspect`; when the instance directory does not exist (os.ErrNotExist) the command returns this error suggesting `limactl create` with the same name. Note the suggestion itself is quirky — creating is normally done via `limactl create <template> --name <inst>`.

Source

Thrown at cmd/limactl/tunnel.go:72

	if err != nil {
		return err
	}
	if tunnelType != "socks" {
		return fmt.Errorf("unknown tunnel type: %#q", tunnelType)
	}
	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
	}

View on GitHub (pinned to dd909d0973)

Solutions

Run `limactl list` to see existing instance names and correct the name
Create the instance first (e.g. `limactl create template://default --name <inst>` then `limactl start <inst>`), then tunnel
Verify LIMA_HOME matches the environment used when the instance was created
If the instance was deleted, recreate it before tunneling

Example fix

// before
limactl tunnel myinst
// error: instance "myinst" does not exist
// after
limactl list
limactl create template://default --name myinst
limactl start myinst
limactl tunnel myinst

Defensive patterns

Strategy: validation

Validate before calling

out, err := exec.Command("limactl", "list", "--json").Output()
if err != nil { return err }
if !strings.Contains(string(out), fmt.Sprintf("%q", instName)) {
	return fmt.Errorf("instance %q not found; create it first", instName)
}

Try / catch

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` first", instName)
	}
	return err
}

Prevention

Run `limactl list` to confirm the instance name before tunneling
Use consistent LIMA_HOME across commands
Create and start the instance before running tunnel

When it happens

Trigger: Running `limactl tunnel <name> ...` where no instance named `<name>` exists under ${LIMA_HOME} (never created, wrong LIMA_HOME, or typo in name).

Common situations: Typos in the instance name; LIMA_HOME pointing at a different instance dir than used for create; instance deleted with `limactl delete`; running tunnel before ever running create/start.

Related errors

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