Skip to content
vGPU OS
Documentation: Troubleshooting

Documentation · Help

Troubleshooting

Safe graphics, network, graphics that do not validate, the rescue console and how to ask for help with the right report.

Alpha

This documentation covers vGPU OS 0.1.2, in alpha. Screens and commands may change between versions; to see the installed version, use vgpu-os version.

Always start with diagnostics: it gathers what is needed to understand the problem and can be shared safely.

vgpu-os diagnostics --save

The USB drive does not boot

  • Check that the firmware is in UEFI mode (not legacy/CSM).
  • Disable Secure Boot.
  • Write the ISO again, to the entire USB drive and in DD mode. See Installation.
  • In the USB drive menu, Advanced / Rescue ... → Check this medium for damage checks the write.

Black screen or corrupted image in the installer

Choose Install vGPU OS (safe graphics) in the USB drive menu. The installation is the same, with basic video; the correct drivers are installed later, in the first setup.

The first setup says there is no internet

vGPU OS needs a wired network with DHCP; Wi-Fi is not supported in this version. Connect the cable to a router that assigns addresses automatically and choose to try again.

If the network card is not recognized, vgpu-os diagnostics shows the Network section. The ISO includes firmware for Realtek and Broadcom (bnx2/bnx2x) cards.

Graphics do not validate (FAIL or SOFTWARE)

  • Run vgpu-os hw validate and vgpu-os hw detect to see each GPU, the driver in use, and whether it responds to Vulkan.
  • Check that the monitor is connected to the GPU you expect: the monitor's GPU must respond to Vulkan.
  • With NVIDIA, check that you authorized the proprietary driver and that Secure Boot is disabled.
  • If you changed the GPU or the monitor port, restart: vGPU OS rereads the hardware on every boot. If needed, rerun the setup with sudo vgpu-os-firstboot --force.

No virtualization (KVM)

If vgpu-os hw validate reports that KVM does not exist, virtualization is disabled in the firmware. Enable Intel VT-x / Virtualization Technology or AMD-V / SVM Mode and restart.

The loading screen does not appear

vgpu-os diagnostics --splash

Explains why it was not drawn. The system works without it.

The computer takes a long time to boot

See the Boot section of vgpu-os diagnostics: it shows the total time and each stage, with the seconds since the kernel started.

Rescue console

When the session does not open, the boot menu has a rescue console:

  1. Press Esc while the computer boots (the menu also comes back on its own after a failed boot).
  2. Choose Advanced options for vGPU OS GNU/Linux → vGPU OS rescue console.
  3. The rescue console is the Debian underneath the appliance. Type vgpu-os diagnostics for the full report, or exit to leave.

On the USB drive, Advanced / Rescue ... → Rescue console (root shell) offers the same kind of access without using the installed system.

Problems with OSX-REIMS or the VMs

VM creation, Reims vGPU, OpenCore, and macOS are OSX-REIMS matters: see the OSX-REIMS troubleshooting (opens in a new tab). osx-reims doctor works the same way on vGPU OS.

Asking for help

Important

vGPU OS has no technical support and is provided without warranty. The #vgpu-os-chat channel is a space for members to help each other: help is voluntary, and there is no guarantee of a reply, a timeframe or a fix. Support requests by email are not answered.

In the #vgpu-os-chat channel on Discord, describe what happened and what appears on screen, and attach the file generated by vgpu-os diagnostics --save, so other members can look into it.