Troubleshooting

This chapter collects common problems and their fixes. When in doubt, start with quantabox status, which summarizes the health of your install.

First Step: Check Status #

quantabox status

Confirm that the Hypervisor is detected (or note it says None), the QEMU version is found, and the data directory is where you expect. Many issues trace back to one of these.

Acceleration Is Not Available #

Symptom: VMs run very slowly; status shows Hypervisor: None.

QuantaBox is falling back to TCG software emulation. Enable native acceleration:

• Windows: Enable Windows Hypervisor Platform (and/or Hyper-V) in Turn Windows features on or off, then reboot. Ensure Intel VT-x / AMD-V is enabled in firmware.
• Linux: Confirm /dev/kvm exists (ls -l /dev/kvm) and that your user is in the kvm group (sudo usermod -aG kvm "$USER", then re-login).
• macOS: Hypervisor.framework is built in; if it is not detected, ensure you are on macOS 13+ and the app has the entitlements it shipped with.

See Installation for full steps.

QEMU Not Found #

Symptom: status shows QEMU: not found; VMs will not start.

• Install QEMU (qemu-system-x86_64 and qemu-img). See Installation.
• If installed in a non-standard path, set the engine location in Settings > Engine.
• On Windows, re-run the installer and include the bundled QEMU component.

A VM Will Not Start #

1. Open the VM's Logs tab (or check the engine log in the VM's folder). It usually states the exact failure.
2. Common causes:
   • No disk attached: a VM needs at least one disk to start.
   • QEMU missing: see QEMU Not Found above.
   • Insufficient host memory: lower the VM's RAM or close other apps.
   • Acceleration mismatch: if you moved the VM from a machine with different acceleration, it may fall back to TCG and run slowly.

The Console Shows "Can't Reach This Page" / No Display #

Symptom: The console area shows a connection error instead of the guest screen.

• Make sure the VM is actually Running (not just selected).
• Click Connect in the console toolbar to retry; QuantaBox also auto-reconnects a few times on its own.
• If the guest has just started, give it a moment to bring up its display.
• If the problem persists, stop and restart the VM and watch the Logs tab.

No Networking Inside the Guest #

• Confirm the adapter is enabled and the cable is connected in Settings > Network.
• For installers that lack virtio drivers, switch the NIC model to Intel PRO/1000 (e1000) for the install, then move to VirtIO-net afterward.
• In NAT mode the guest gets internet automatically; to reach the guest from the host, configure SSH port forwarding.
• In Bridged mode, ensure the bridged physical interface is the one actually connected to your network.

Cannot SSH Into a VM #

• SSH info appears only when the VM is Running and a host port is forwarded to guest port 22. See Networking.
• Confirm an SSH server is installed and running inside the guest.
• Use the exact command/port from the SSH tab. The port is allocated per run.

Disk Resize Did Not Add Space in the Guest #

Resizing in QuantaBox only enlarges the disk container. You must extend the partition and filesystem inside the guest afterward (for example, growpart + resize2fs on Linux, or Disk Management on Windows). See Storage and Disks.

Forgotten or Lost Encryption Keys #

Encrypted disks and packages require their key material. Always back up your key vault with your VMs. See Post-Quantum Encryption.

A Console Window Flashes When Using the App #

Modern QuantaBox suppresses helper console windows on Windows. If you see stray terminal windows, ensure you are running the current release; older builds could briefly show a console when enumerating devices or running disk tools.

Gathering Diagnostics for a Bug Report #

When reporting an issue, include:

• The output of quantabox status.
• Your OS and version, and whether acceleration is enabled.
• The relevant VM's Logs tab contents.
• Steps to reproduce, and what you expected versus what happened.

Run with extra logging for more detail:

RUST_LOG=debug quantabox <command>

Still Stuck? #

See the FAQ, the Technical Documentation, or open an issue on the project repository with the diagnostics above.