{"record":{"id":"02e47b171ec8a9dc","repo":"lima-vm/lima","slug":"failed-to-create-virtio-sound-device-configuration","errorCode":null,"errorMessage":"failed to create virtio sound device configuration: %w","messagePattern":"failed to create virtio sound device configuration: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/vz/vm_darwin.go","lineNumber":791,"sourceCode":"\n\taudioDev := *y.Audio.Device\n\taudioInterface := *y.Audio.Interface\n\n\t// If the user explicitly asks for HDA, we gracefully ignore it.\n\tif audioInterface == \"hda\" {\n\t\tlogrus.Warn(\"VZ driver natively uses virtio-sound. Ignoring 'hda' interface request.\")\n\t}\n\n\tswitch audioDev {\n\tcase \"vz\", \"default\":\n\t\toutputStream, err := vz.NewVirtioSoundDeviceHostOutputStreamConfiguration()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create host audio output stream: %w\", err)\n\t\t}\n\n\t\tsoundDeviceConfiguration, err := vz.NewVirtioSoundDeviceConfiguration()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to create virtio sound device configuration: %w\", err)\n\t\t}\n\t\tsoundDeviceConfiguration.SetStreams(outputStream)\n\t\tconfig.SetAudioDevicesVirtualMachineConfiguration([]vz.AudioDeviceConfiguration{\n\t\t\tsoundDeviceConfiguration,\n\t\t})\n\t\treturn nil\n\tcase \"\", \"none\":\n\t\treturn nil\n\tdefault:\n\t\treturn fmt.Errorf(\"unexpected audio device %#q\", *inst.Config.Audio.Device)\n\t}\n}\n\nfunc attachOtherDevices(inst *limatype.Instance, vmConfig *vz.VirtualMachineConfiguration) error {\n\tentropyConfig, err := vz.NewVirtioEntropyDeviceConfiguration()\n\tif err != nil {\n\t\treturn err\n\t}","sourceCodeStart":773,"sourceCodeEnd":809,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/vz/vm_darwin.go#L773-L809","documentation":"attachAudio wraps the error returned by vz.NewVirtioSoundDeviceConfiguration() when the Virtualization framework fails to allocate a virtio sound device configuration for the VM. This is a host-side Virtualization.framework API failure, almost always because the API returned an internal error (e.g. unsupported configuration or resource exhaustion). Lima propagates it while building the VZ VM configuration in createVM.","triggerScenarios":"Audio device is configured (audio.device not \"none\") and the call vz.NewVirtioSoundDeviceConfiguration() returns a non-nil error during VM configuration creation.","commonSituations":"Running on macOS versions where the sound device configuration API misbehaves; rare Virtualization.framework internal failures; usually not a Lima config problem.","solutions":["Retry starting the instance — this is usually a transient Virtualization.framework error","Set audio.device to \"none\" in the Lima YAML to skip sound device creation entirely","Update macOS to the latest version so the Virtualization.framework bug is fixed","Check the wrapped error (%w) for the underlying cause and report to lima-vm/lima if persistent"],"exampleFix":"// before (lima.yaml)\naudio:\n  device: vboxhda\n// after\naudio:\n  device: none","handlingStrategy":"fallback","validationCode":"// lima.yaml\ncfg := yaml.MapSlice{...}\nif audioDev, ok := cfg[\"audio.device\"]; ok && audioDev != \"none\" && audioDev != \"vboxhda\" && audioDev != \"pcspk\" && audioDev != \"\" {\n    // unsupported by lima; set to \"none\"\n}","typeGuard":null,"tryCatchPattern":"err := limactlStart()\nif err != nil && strings.Contains(err.Error(), \"failed to create virtio sound device configuration\") {\n    // disable audio in config and retry\n    setAudioDeviceNone(); err = limactlStart()\n}","preventionTips":["Leave audio.device unset (defaults to \"none\") unless sound is required","Keep macOS updated to avoid Virtualization.framework bugs","Validate config with `limactl validate` before starting"],"tags":["audio","vz","macos","virtualization-framework"],"backgroundTag":"vz-device-creation-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}