Skip to content

[Feature]: Add a troubleshooting page for QEMU and firmware not found #462

Description

@rogkne

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions