network mode %#q does not support specifying gateway

Error message

network mode %#q does not support specifying gateway

What it means

In bridged network mode the guest attaches directly to a physical interface, so gateway configuration is not supported; `limactl network create --mode bridged --gateway <ip>` rejects the gateway flag with this error at cmd/limactl/network.go:206. Bridged mode requires --interface instead.

Source

Thrown at cmd/limactl/network.go:206

		return err
	}

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

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

	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 {

View on GitHub (pinned to dd909d0973)

Solutions

Drop the --gateway flag for bridged mode: `limactl network create <name> --mode bridged --interface <if>`
Use mode host (or routed) if you actually need to specify a gateway
Set static IPs/gateways inside the guest or via lima.yaml's subnet config rather than the network definition

Example fix

// before
limactl network create br0 --mode bridged --gateway 192.168.1.1 --interface en0
// after
limactl network create br0 --mode bridged --interface en0

Defensive patterns

Strategy: validation

Validate before calling

MODE=bridged; GW=192.168.1.1
[ "$MODE" = "bridged" ] && [ -n "$GW" ] && { echo "bridged mode must not set --gateway"; exit 1; }

Try / catch

if err := cmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "does not support specifying gateway") {
		fmt.Fprintln(os.Stderr, "remove --gateway for bridged mode; use --interface")
		os.Exit(2)
	}
	os.Exit(1)
}

Prevention

Remember mode/flag matrix: bridged → interface, no gateway; host/routed → gateway required
Build per-mode command templates in scripts
Avoid passing optional flags unconditionally with empty defaults

When it happens

Trigger: `limactl network create <name> --mode bridged --gateway <ip> ...` — any bridged-mode create that passes a non-empty --gateway value.

Common situations: Copy-pasting a create command from a routed/host-network example into a bridged one; assuming gateway/DNS settings apply in bridged mode because the machine has a static gateway config; scripting that always passes --gateway.

Related errors

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