lima-vm/lima · error

network mode %#q requires specifying interface

Error message

network mode %#q requires specifying interface

What it means

All non-bridged modes that require explicit topology (host, routed) must be given a gateway address; if --gateway is empty, networkCreateAction returns this error at cmd/limactl/network.go:209 (the default branch of the mode switch). The gateway is written into the network's yq definition as part of creation.

Source

Thrown at cmd/limactl/network.go:209

	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 {
			return fmt.Errorf("failed to parse CIDR %#q: %w", gateway, err)
		}
		if gwIP.IsUnspecified() || gwIP.IsLoopback() {

View on GitHub (pinned to dd909d0973)

Solutions

  1. Add the flag: `limactl network create <name> --mode host --gateway <subnet-gateway-ip>`
  2. Use --mode shared if you don't want to manage gateways manually
  3. Ensure the variable supplying --gateway is set and non-empty in scripts

Example fix

// before
limactl network create lima-net --mode host
# Error: network mode "host" requires specifying gateway
// after
limactl network create lima-net --mode host --gateway 192.168.5.1
Defensive patterns

Strategy: validation

Validate before calling

MODE=host; GW="${GATEWAY:-}"
[ "$MODE" = "host" -o "$MODE" = "routed" ] && [ -z "$GW" ] && { echo "$MODE requires --gateway"; exit 1; }

Try / catch

if err := cmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "requires specifying gateway") {
		fmt.Fprintln(os.Stderr, "add e.g. --gateway 192.168.5.1 for host/routed mode")
		os.Exit(2)
	}
	os.Exit(1)
}

Prevention

When it happens

Trigger: `limactl network create <name> --mode host` (or routed) without --gateway, or with --gateway "" coming from an empty shell variable.

Common situations: Scripts where a GATEWAY variable is unset; forgetting that host/routed modes differ from bridged/shared mode requirements; copying a shared-mode example command for a host-mode network.

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

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