Fixing bhyve VMs That Refuse to Boot With UEFI Firmware

bhyve supports two distinct boot paths: the legacy path, where bhyveload(8) or grub-bhyve loads a guest kernel directly from the host before the guest ever runs its own boot loader, and UEFI firmware boot, where bhyve hands control to an actual UEFI firmware image (BHYVE_UEFI.fd, typically from the sysutils/edk2-bhyve port or base-system equivalent depending on release) that then boots the guest the way real UEFI-based hardware would. UEFI boot is necessary for guests that expect real UEFI services — most modern Windows guests, and Linux distributions that specifically expect an EFI System Partition — and it fails differently than legacy boot problems do, which makes generic bhyve troubleshooting advice often point in the wrong direction.

Confirm which firmware path is actually in use

Before diagnosing anything else, confirm the VM is actually being launched with UEFI firmware rather than accidentally falling back to legacy boot. A UEFI-booted bhyve invocation includes an explicit firmware bootrom argument:

bhyve -c 2 -m 4G \
  -l bootrom,/usr/local/share/uefi-firmware/BHYVEUEFI.fd \
  ... 

If this argument is missing or the path is wrong, bhyve will either fail immediately with a clear “bootrom” error, or — depending on how the invocation script is structured — silently fall through to a different boot path than intended. Confirm the firmware file itself actually exists at the referenced path and is readable by the user running bhyve; a missing package (edk2-bhyve not installed, or installed to a different path than the launch script expects) is a surprisingly common root cause disguised as a “boot failure.”

The VM appears to hang with no console output at all

This is the most common UEFI-specific symptom, and it usually isn’t actually a hang — it’s a display/console configuration mismatch. UEFI firmware wants a framebuffer device to write its early boot output to, and if bhyve wasn’t given one (-s-numbered fbuf device), the firmware may be running and progressing through boot entirely correctly while producing output on a virtual GPU nothing is watching:

-s 29,fbuf,tcp=0.0.0.0:5900,w=1024,h=768
-s 30,xhci,tablet

Connect a VNC client to the configured port and address rather than relying on the serial/terminal output you’d get from a legacy-boot guest — UEFI’s early firmware screens (and often a guest OS’s own graphical boot splash) simply don’t appear on a serial console the way legacy BIOS text-mode output does. A VM that “hangs with nothing on screen” when checked via bhyvectl or a serial connection frequently turns out to be booting completely normally once actually viewed over VNC.

The firmware boots but can’t find a bootable OS

If VNC confirms the UEFI firmware itself is running (you’ll typically see a firmware boot menu or splash if boot doesn’t proceed automatically) but it reports no bootable device, the most common cause is a disk image that wasn’t actually partitioned with a GPT/EFI System Partition layout the firmware recognizes — a raw disk image created for a legacy-BIOS guest, with an MBR partition table and no ESP, genuinely has nothing a UEFI firmware can boot from, regardless of what’s inside the guest filesystem.

Confirm the guest’s virtual disk was actually installed with (or converted to) a GPT layout including an EFI System Partition. For a fresh install, this usually means simply installing the guest OS with UEFI firmware active from the start (most modern installers correctly detect UEFI and partition accordingly) rather than attempting to boot an existing legacy-partitioned image under UEFI after the fact — converting an existing MBR-partitioned installation to GPT+ESP after the fact is possible but nontrivial and OS-specific, and re-installing under the correct firmware mode from the start is usually faster than trying to convert.

Guest boots partially, then resets or hangs mid-boot

A guest that gets partway into its own OS boot sequence (past the UEFI firmware itself) and then hangs or silently reboots is less likely to be a bhyve/UEFI-specific problem and more likely a standard guest resource or configuration issue that happens to be surfacing at this stage — commonly insufficient memory allocated to the guest, a CPU count mismatch with what the guest OS’s installed kernel expects, or a missing/misconfigured virtio driver inside the guest for whatever storage or network device bhyve is presenting.

Check whether the guest is configured with virtio-blk or virtio-net devices the guest OS actually has drivers for (this is a common problem specifically with older or minimal-install Linux guests lacking virtio modules, and with Windows guests that need the virtio driver ISO attached during installation before they can see virtio storage at all):

-s 4,virtio-blk,/path/to/disk.img
-s 5,virtio-net,tap0

If a guest simply can’t see its own boot disk because it lacks the virtio-blk driver, this presents as “boots, then nothing happens” in a way that’s easy to misattribute to the UEFI firmware itself rather than to a driver gap one layer up.

Confirming firmware version/path issues specifically

If none of the above resolves it, confirm the specific bootrom file referenced is actually a version compatible with the bhyve/FreeBSD release in use — the edk2-bhyve package is versioned and tied to specific FreeBSD release support windows, and using a bootrom file left over from an older port version after a system upgrade (rather than reinstalled/updated alongside it) can produce boot failures that look identical to a configuration problem but are actually a stale-firmware-binary problem:

pkg info edk2-bhyve
pkg upgrade edk2-bhyve

Reinstalling the port after a FreeBSD version upgrade, rather than assuming an already-installed bootrom file remains correct indefinitely, resolves this category cleanly and is worth doing preemptively after any base system upgrade on a host that runs UEFI bhyve guests.