What causes "network %#q already exists" in lima-vm/lima?

Inspect the existing entry: `limactl network list` or read networks.yaml, and skip creation if it's already correct

network %#q already exists

Error message

network %#q already exists

What it means

`limactl network create <name>` refuses to create a network whose name already exists in networks.yaml. After LoadConfig ensures the file exists, the action checks config.Networks[name] and returns this error from cmd/limactl/network.go:182. networks.yaml holds named virtual networks shared across instances.

Source

Thrown at cmd/limactl/network.go:182

	flags.String("mode", networks.ModeUserV2, "mode")
	_ = cmd.RegisterFlagCompletionFunc("mode", func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
		return networks.Modes, cobra.ShellCompDirectiveNoFileComp
	})
	flags.String("gateway", "", "gateway, e.g., \"192.168.42.1/24\"")
	flags.String("interface", "", "interface for bridged mode")
	_ = cmd.RegisterFlagCompletionFunc("interface", bashFlagCompleteNetworkInterfaceNames)
	return cmd
}

func networkCreateAction(cmd *cobra.Command, args []string) error {
	name := args[0]
	// LoadConfig ensures existence of networks.yaml
	config, err := networks.LoadConfig()
	if err != nil {
		return err
	}
	if _, ok := config.Networks[name]; ok {
		return fmt.Errorf("network %#q already exists", name)
	}

	flags := cmd.Flags()
	mode, err := flags.GetString("mode")
	if err != nil {
		return err
	}

	gateway, err := flags.GetString("gateway")
	if err != nil {
		return err
	}

	intf, err := flags.GetString("interface")
	if err != nil {
		return err
	}

View on GitHub (pinned to dd909d0973)

Solutions

Inspect the existing entry: `limactl network list` or read networks.yaml, and skip creation if it's already correct
Choose a different name for the new network
Modify the existing network with `limactl network edit <name>` instead of create
Make scripts idempotent: check existence before `network create`

Example fix

// before
limactl network create shared
# Error: network "shared" already exists
// after
limactl network list | grep -q shared || limactl network create shared --mode shared

Defensive patterns

Strategy: validation

Validate before calling

name="shared"
limactl network list 2>/dev/null | grep -qw "$name" && echo "network $name exists, skipping create" || limactl network create "$name" --mode shared

Try / catch

if err := networkCreateAction(cmd, args); err != nil {
	if strings.Contains(err.Error(), "already exists") {
		return nil // treat as idempotent success
	}
	return err
}

Prevention

Make provisioning scripts idempotent: list/grep before create
Use `limactl network edit` to change existing networks
Keep network names unique and namespaced (e.g. team-net-1)

When it happens

Trigger: `limactl network create <name> ...` where <name> is already a key under .networks in $LIMA_HOME/_config/networks.yaml (created earlier, manually, or by another tool).

Common situations: Re-running an idempotent provisioning script that recreates networks; name collision with a default/manual network; typos reusing an existing name unintentionally.

Related errors

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