networks.yaml '%s' configuration is only supported on macOS

Error message

networks.yaml '%s' configuration is only supported on macOS right now

What it means

Lima's vz driver refuses to start when a lima.yaml `networks` entry references a named network (`networks.yaml` config, i.e. a `Lima:` field) because the vz driver only implements that on macOS. The check exists in vm_darwin.go, so hitting it means the vz driver path was reached on a non-darwin GOOS (or the check guards a shared code path) and the network definition required socketVMNet-style macOS bridging.

Source

Thrown at pkg/driver/vz/vm_darwin.go:489

				if i == firstUsernetIndex {
					continue
				}
				vzSock, err := usernet.Sock(nw.Lima, usernet.FDSock)
				if err != nil {
					return err
				}
				clientFile, err := PassFDToUnix(vzSock)
				if err != nil {
					return err
				}
				networkConfig, err := newVirtioFileNetworkDeviceConfiguration(clientFile, nw.MACAddress)
				if err != nil {
					return err
				}
				configurations = append(configurations, networkConfig)
			} else {
				if runtime.GOOS != "darwin" {
					return fmt.Errorf("networks.yaml '%s' configuration is only supported on macOS right now", nw.Lima)
				}
				socketVMNetOk, err := nwCfg.IsDaemonInstalled(networks.SocketVMNet)
				if err != nil {
					return err
				}
				if socketVMNetOk {
					logrus.Debugf("Using socketVMNet (%#q)", nwCfg.Paths.SocketVMNet)
					sock, err := networks.Sock(nw.Lima)
					if err != nil {
						return err
					}

					clientFile, err := DialQemu(ctx, sock)
					if err != nil {
						return err
					}
					networkConfig, err := newVirtioFileNetworkDeviceConfiguration(clientFile, nw.MACAddress)
					if err != nil {

View on GitHub (pinned to dd909d0973)

Solutions

Remove the `lima:`-named network entry from the instance's lima.yaml, or switch to a driver-supported network mode (e.g. default slirp/ngveth) on this OS
Run the instance on a macOS host, where the vz driver supports networks.yaml networks (install socket-vmnet if bridging is needed)
Use the qemu driver instead of vz if you need that network topology on this platform

Example fix

// before
networks:
  - lima: shared
// after
networks: []   # or use default user-mode networking on non-macOS

Defensive patterns

Strategy: validation

Validate before calling

if runtime.GOOS != "darwin" {
    for _, nw := range cfg.Networks {
        if nw.Lima != "" {
            return fmt.Errorf("named network %q requires macOS with the vz driver", nw.Lima)
        }
    }
}

Try / catch

if err := startInstance(cfg); err != nil {
    if strings.Contains(err.Error(), "only supported on macOS") {
        // fall back to default networking or qemu driver
    }
}

Prevention

Keep per-OS lima.yaml variants or template conditionals for networks
Validate config with `limactl start --print` on the target OS before launching
Document that named networks are macOS/vz-only in team templates

When it happens

Trigger: Creating/starting an instance with the vz driver where `networks` contains an entry with a `lima:` name (a networks.yaml-defined network) on a platform where runtime.GOOS != darwin; attachNetwork is invoked from createVM.

Common situations: Copying a Linux/macOS co-developed lima.yaml that uses a shared named network onto a non-macOS host; CI matrices running the same template across OSes; stale config referencing networks only valid for vz on macOS.

Related errors

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