FreeBSD 14 – bhyve VM fails to boot from configured disk image – Fix & Prevention

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

VM exits at startup or loops in firmware shell, blocking tenant workloads.

Environment & Reproduction

Typical when bootrom, disk bus type, or image path arguments are mismatched.

bhyvectl --vm=vm1 --destroy
bhyve -H -P -c 2 -m 2G -s 0,hostbridge -s 4,virtio-blk,/zroot/vm1.img vm1

Root Cause Analysis

Incorrect loader/UEFI setup or invalid disk mapping prevents guest boot chain from executing.

Quick Triage

Validate vm image readability and UEFI firmware path.

ls -la /zroot/vm1.img
file /zroot/vm1.img
ls -la /usr/local/share/uefi-firmware

Step-by-Step Diagnosis

Use explicit bhyve stderr output and inspect vm-bhyve config fields.

bhyve -w -H -P -A -s 0,hostbridge -s 31,lpc -l com1,stdio vm1
cat /zroot/vm/.templates/* 2>/dev/null

Solution – Primary Fix

Set correct bootrom and disk device options, then recreate VM runtime state.

bhyvectl --vm=vm1 --destroy || true
cp -a /usr/local/etc/vm-bhyve /usr/local/etc/vm-bhyve.bak
vm configure vm1
vm start vm1

Solution – Alternative Approaches

Convert disk image format or switch controller type between ahci and virtio-blk based on guest expectations.

Verification & Acceptance Criteria

Guest reaches bootloader and operating system startup consistently.

vm list
vm console vm1

Rollback Plan

Restore prior VM config and image snapshot if boot regression persists.

cp -a /usr/local/etc/vm-bhyve.bak/* /usr/local/etc/vm-bhyve/

Prevention & Hardening

Template known-good VM definitions and enforce config validation before deployment.

Related Errors & Cross-Refs

Related to nested virtualization constraints and missing vmm kernel module state.

Related tutorial: View the step-by-step tutorial for freebsd-14.

View all freebsd-14 tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

bhyve(8), bhyvectl(8), and vm-bhyve operational documentation.