failed to create virtio sound device configuration: %w

Error message

failed to create virtio sound device configuration: %w

What it means

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.

Source

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

	audioDev := *y.Audio.Device
	audioInterface := *y.Audio.Interface

	// If the user explicitly asks for HDA, we gracefully ignore it.
	if audioInterface == "hda" {
		logrus.Warn("VZ driver natively uses virtio-sound. Ignoring 'hda' interface request.")
	}

	switch audioDev {
	case "vz", "default":
		outputStream, err := vz.NewVirtioSoundDeviceHostOutputStreamConfiguration()
		if err != nil {
			return fmt.Errorf("failed to create host audio output stream: %w", err)
		}

		soundDeviceConfiguration, err := vz.NewVirtioSoundDeviceConfiguration()
		if err != nil {
			return fmt.Errorf("failed to create virtio sound device configuration: %w", err)
		}
		soundDeviceConfiguration.SetStreams(outputStream)
		config.SetAudioDevicesVirtualMachineConfiguration([]vz.AudioDeviceConfiguration{
			soundDeviceConfiguration,
		})
		return nil
	case "", "none":
		return nil
	default:
		return fmt.Errorf("unexpected audio device %#q", *inst.Config.Audio.Device)
	}
}

func attachOtherDevices(inst *limatype.Instance, vmConfig *vz.VirtualMachineConfiguration) error {
	entropyConfig, err := vz.NewVirtioEntropyDeviceConfiguration()
	if err != nil {
		return err
	}

View on GitHub (pinned to dd909d0973)

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

Example fix

// before (lima.yaml)
audio:
  device: vboxhda
// after
audio:
  device: none

Defensive patterns

Strategy: fallback

Validate before calling

// lima.yaml
cfg := yaml.MapSlice{...}
if audioDev, ok := cfg["audio.device"]; ok && audioDev != "none" && audioDev != "vboxhda" && audioDev != "pcspk" && audioDev != "" {
    // unsupported by lima; set to "none"
}

Try / catch

err := limactlStart()
if err != nil && strings.Contains(err.Error(), "failed to create virtio sound device configuration") {
    // disable audio in config and retry
    setAudioDeviceNone(); err = limactlStart()
}

Prevention

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

When it happens

Trigger: Audio device is configured (audio.device not "none") and the call vz.NewVirtioSoundDeviceConfiguration() returns a non-nil error during VM configuration creation.

Common situations: Running on macOS versions where the sound device configuration API misbehaves; rare Virtualization.framework internal failures; usually not a Lima config problem.

Related errors

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