lima-vm/lima · error

invalid mode %#q for network %#q: %w

Error message

invalid mode %#q for network %#q: %w

What it means

A network's `mode` (e.g. host, user-v2, bridged) is embedded in generated sudoers/daemon arguments, so it must be a valid identifier; otherwise validation fails quoting both the mode and network name.

Source

Thrown at pkg/networks/validate.go:40

	// verbatim into the sudoers file (sudoers.go) and into the socket_vmnet
	// command that reconcile.go runs via sudo after splitting it on spaces
	// (commands.go). A value with whitespace injects an extra argument, and a
	// newline in a network name adds an arbitrary directive to the generated
	// sudoers file, so require them to be valid identifiers. Interface is empty
	// for non-bridged networks, and group defaults to "admin" when unset, so
	// only validate those when a value is actually present.
	if c.Group != "" {
		if err := identifiers.Validate(c.Group); err != nil {
			return fmt.Errorf("invalid group %#q: %w", c.Group, err)
		}
	}
	for name, nw := range c.Networks {
		if err := identifiers.Validate(name); err != nil {
			return fmt.Errorf("invalid network name %#q: %w", name, err)
		}
		if nw.Mode != "" {
			if err := identifiers.Validate(nw.Mode); err != nil {
				return fmt.Errorf("invalid mode %#q for network %#q: %w", nw.Mode, name, err)
			}
		}
		if nw.Interface != "" {
			if err := identifiers.Validate(nw.Interface); err != nil {
				return fmt.Errorf("invalid interface %#q for network %#q: %w", nw.Interface, name, err)
			}
		}
	}

	// validate all paths.* values
	paths := reflect.ValueOf(&c.Paths).Elem()
	pathsMap := make(map[string]string, paths.NumField())
	var socketVMNetNotFound bool
	for i := range paths.NumField() {
		// extract YAML name from struct tag; strip options like "omitempty"
		name := paths.Type().Field(i).Tag.Get("yaml")
		if i := strings.IndexRune(name, ','); i > -1 {
			name = name[:i]

View on GitHub (pinned to dd909d0973)

Solutions

1. Fix the `mode` value to one of the supported identifiers (host, shared, bridged, user-v2).
2. Check YAML indentation so the mode belongs to the intended network entry.
3. Re-run limactl start / networks.Validate() after the edit.
4. If you intended a bridged interface, configure it via `interface:` not `mode:`.

Example fix

# before (networks.yaml)
networks:
  lima-user-v2:
    mode: "user v2"
# after
networks:
  lima-user-v2:
    mode: user-v2

const validModes = ['host','shared','bridged','user-v2'];
function validateMode(mode, name) {
  if (!mode) return null;
  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(mode)) return `invalid mode '${mode}' for network ${name}`;
  if (!validModes.includes(mode)) return `unknown mode '${mode}' (expected one of ${validModes.join(', ')})`;
  return null;
}

function isValidMode(mode) {
  return !mode || (typeof mode === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(mode));
}

When it happens

Trigger: Setting `mode:` for a network in networks.yaml to a misspelled or malformed value (spaces, symbols, wrong case tricks) and calling networks.Validate().

Common situations: Typos like 'user v2' or 'host\n'; adding a new experimental mode string with invalid characters; copy-paste from docs with trailing whitespace.

Related errors

• invalid group %#q: %w
• invalid network name %#q: %w
• invalid interface %#q for network %#q: %w
• path %#q is not an absolute path
• path %#q contains whitespace

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