network mode %#q does not support specifying interface

Error message

network mode %#q does not support specifying interface

What it means

For non-bridged network modes the interface field is derived/generated by Lima, so a user-supplied --interface is rejected. The guard right after the gateway check aborts the create if --interface is set while mode is not bridged.

Source

Thrown at cmd/limactl/network.go:218

	ctx := cmd.Context()

	switch mode {
	case networks.ModeBridged:
		if gateway != "" {
			return fmt.Errorf("network mode %#q does not support specifying gateway", mode)
		}
		if intf == "" {
			return fmt.Errorf("network mode %#q requires specifying interface", mode)
		}
		yq := fmt.Sprintf(`.networks.%q = {"mode":%q,"interface":%q}`, name, mode, intf)
		return networkApplyYQ(ctx, yq)
	default:
		if gateway == "" {
			return fmt.Errorf("network mode %#q requires specifying gateway", mode)
		}
		if intf != "" {
			return fmt.Errorf("network mode %#q does not support specifying interface", mode)
		}
		if !strings.Contains(gateway, "/") {
			gateway += "/24"
		}
		gwIP, gwMask, err := net.ParseCIDR(gateway)
		if err != nil {
			return fmt.Errorf("failed to parse CIDR %#q: %w", gateway, err)
		}
		if gwIP.IsUnspecified() || gwIP.IsLoopback() {
			return fmt.Errorf("invalid IP address: %v", gwIP)
		}
		gwMaskStr := "255.255.255.0"
		if gwMask != nil {
			gwMaskStr = net.IP(gwMask.Mask).String()
		}
		// TODO: check IP range collision

		yq := fmt.Sprintf(`.networks.%q = {"mode":%q,"gateway":%q,"netmask":%q,"interface":%q}`, name, mode, gwIP.String(), gwMaskStr, intf)

View on GitHub (pinned to dd909d0973)

Solutions

Remove the --interface flag for this mode: `limactl network create mynet --gateway 192.168.5.1`
If a specific host interface is needed, use --mode bridged (which requires --interface and forbids --gateway)
Run `limactl network create --help` to confirm mode/flag compatibility

Example fix

// before
limactl network create lima-shared --mode shared --gateway 192.168.104.1 --interface en0
// after
limactl network create lima-shared --mode shared --gateway 192.168.104.1

Defensive patterns

Strategy: validation

Validate before calling

if [ "$mode" = "bridged" ]; then
  require interface
else
  unset interface   # interface is only valid for bridged mode
fi

Prevention

Only pass --interface together with --mode bridged
Never mix --interface and --gateway in one create call
Keep one script template per mode instead of a shared one

When it happens

Trigger: Running `limactl network create <name> --gateway <cidr> --interface <if>` with --mode anything other than bridged (or default mode).

Common situations: Users always adding --interface out of habit from bridged mode; scripts templated for bridged networks reused for gateway-based modes; misunderstanding that interface only applies to bridged mode.

Related errors

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