lima-vm/lima · error

network mode %#q requires specifying gateway

Error message

network mode %#q requires specifying gateway

What it means

`limactl network create` validates flag combinations per network mode. Any mode other than "bridged" (the default switch case) requires a --gateway value, because the gateway IP/netmask is written into the networks.yaml entry for that mode. If --gateway is empty for such a mode, the command aborts before applying the yq edit.

Source

Thrown at cmd/limactl/network.go:215

	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 {
			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()
		}

View on GitHub (pinned to dd909d0973)

Solutions

1. Pass --gateway with a valid CIDR, e.g. `limactl network create mynet --gateway 192.168.5.1`
2. If bridged networking was intended, pass --mode bridged plus --interface <host-if> instead of a gateway
3. Check `limactl network create --help` for the mode-specific flag requirements

Example fix

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

gateway="192.168.104.1"
mode="shared"
if [ "$mode" != "bridged" ] && [ -z "$gateway" ]; then
  echo "--gateway is required for mode $mode" >&2; exit 1
fi

When it happens

Trigger: Running `limactl network create <name>` (or with --mode set to a non-bridged mode such as host/shared) without passing --gateway.

Common situations: Users copying a bridged-mode example (which forbids gateway) and applying it to another mode; scripts omitting --gateway because bridged does not need it; newer modes added to the default branch that users are unaware require a gateway.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• network %#q already exists
• network mode %#q does not support specifying gateway
• network mode %#q requires specifying interface
• network mode %#q does not support specifying interface
• `limactl network delete` currently always requires `--force`

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