{"record":{"id":"030cba4415aa5737","repo":"lima-vm/lima","slug":"networks-yaml-s-configuration-is-only-supported-030cba","errorCode":null,"errorMessage":"networks.yaml '%s' configuration is only supported on macOS right now","messagePattern":"networks\\.yaml '(.+?)' configuration is only supported on macOS right now","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/vz/vm_darwin.go","lineNumber":489,"sourceCode":"\t\t\t\tif i == firstUsernetIndex {\n\t\t\t\t\tcontinue\n\t\t\t\t}\n\t\t\t\tvzSock, err := usernet.Sock(nw.Lima, usernet.FDSock)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t\tclientFile, err := PassFDToUnix(vzSock)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t\tnetworkConfig, err := newVirtioFileNetworkDeviceConfiguration(clientFile, nw.MACAddress)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t\tconfigurations = append(configurations, networkConfig)\n\t\t\t} else {\n\t\t\t\tif runtime.GOOS != \"darwin\" {\n\t\t\t\t\treturn fmt.Errorf(\"networks.yaml '%s' configuration is only supported on macOS right now\", nw.Lima)\n\t\t\t\t}\n\t\t\t\tsocketVMNetOk, err := nwCfg.IsDaemonInstalled(networks.SocketVMNet)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t\tif socketVMNetOk {\n\t\t\t\t\tlogrus.Debugf(\"Using socketVMNet (%#q)\", nwCfg.Paths.SocketVMNet)\n\t\t\t\t\tsock, err := networks.Sock(nw.Lima)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\n\t\t\t\t\tclientFile, err := DialQemu(ctx, sock)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\t\t\t\t\tnetworkConfig, err := newVirtioFileNetworkDeviceConfiguration(clientFile, nw.MACAddress)\n\t\t\t\t\tif err != nil {","sourceCodeStart":471,"sourceCodeEnd":507,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/vz/vm_darwin.go#L471-L507","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nnetworks:\n  - lima: shared\n// after\nnetworks: []   # or use default user-mode networking on non-macOS","handlingStrategy":"validation","validationCode":"if runtime.GOOS != \"darwin\" {\n    for _, nw := range cfg.Networks {\n        if nw.Lima != \"\" {\n            return fmt.Errorf(\"named network %q requires macOS with the vz driver\", nw.Lima)\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := startInstance(cfg); err != nil {\n    if strings.Contains(err.Error(), \"only supported on macOS\") {\n        // fall back to default networking or qemu driver\n    }\n}","preventionTips":["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"],"tags":["network","vz-driver","macos","platform-support"],"backgroundTag":"network-config-unsupported-on-platform","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}