Feature Description
Add a troubleshooting page that maps the most common first run failure, a missing QEMU
or UEFI firmware, to the steps that fix it.
Use Case
When QEMU or the firmware is not present, cubic stops with a QEMU not found error. The
QEMU detection page explains where cubic searches, but nothing connects the visible
error to a fix, so a new user has to infer it. A short troubleshooting entry would turn
a dead end into a clear next step.
Proposed Solution
Add a page under docs/troubleshooting/ that names the error, shows how to install
QEMU and the firmware (OVMF for amd64 and AAVMF or edk2 for arm64) per platform, and
points at CUBIC_QEMU_DIR and the CUBIC_QEMU_FW_* variables for non standard
locations. Link it from the site index. While in the recovery guide, add a note that
the snap package strips qemu-nbd, so snap users need their distribution's
qemu-utils for the block device method.
Additional Context
docs/internals/qemu_detection.rst already documents the search order to link to
docs/troubleshooting/recover_disk.rst is where the qemu-nbd note belongs
Feature Description
Add a troubleshooting page that maps the most common first run failure, a missing QEMU
or UEFI firmware, to the steps that fix it.
Use Case
When QEMU or the firmware is not present, cubic stops with a QEMU not found error. The
QEMU detection page explains where cubic searches, but nothing connects the visible
error to a fix, so a new user has to infer it. A short troubleshooting entry would turn
a dead end into a clear next step.
Proposed Solution
Add a page under
docs/troubleshooting/that names the error, shows how to installQEMU and the firmware (OVMF for amd64 and AAVMF or edk2 for arm64) per platform, and
points at
CUBIC_QEMU_DIRand theCUBIC_QEMU_FW_*variables for non standardlocations. Link it from the site index. While in the recovery guide, add a note that
the snap package strips
qemu-nbd, so snap users need their distribution'sqemu-utilsfor the block device method.Additional Context
docs/internals/qemu_detection.rstalready documents the search order to link todocs/troubleshooting/recover_disk.rstis where theqemu-nbdnote belongs