Documentation · Help
Troubleshooting
Safe graphics, network, graphics that do not validate, the rescue console and how to ask for help with the right report.
This documentation covers vGPU OS 0.3.0, 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 --saveThe 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 damagechecks 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 validateandvgpu-os hw detectto 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 driver and that Secure Boot is disabled. To install the driver again, run
sudo vgpu-os-hw provision. - 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.
The VM does not use the NVIDIA GPU
- The card must be on NVIDIA's driver: in
vgpu-os hw validate, the GPU should show thenvidiadriver, with the VM memory and CUDA driver lines OK. With nouveau, the community's open driver, VMs do not run on it. - The driver is built on the computer and is not signed: with Secure Boot on, the kernel does not load it. Turn Secure Boot off in the firmware and restart.
- If you declined the driver during the first setup, run
sudo vgpu-os-hw provisionto be asked again.
See GPUs and drivers.
The web panel does not open
- Use the address shown on the OSX-REIMS console, with
https://, on a computer on the same network. - The first time, the browser shows a security warning, because the certificate is created on the computer itself. Accept the warning to continue; the fingerprint to compare is in
/etc/vgpu-os/webui/tls.sha256. - Until OSX-REIMS finishes its preparation, the panel shows Initial setup pending: finish it on vGPU OS' monitor.
- To sign in, use the user
vgpu-userand the password set at installation. After many wrong attempts, the panel waits a few seconds before accepting another.
See Web panel.
The monitor went black after changing the mode
Do nothing: the mode on trial goes back to the previous one by itself after 15 seconds. If a saved mode no longer works, run vgpu-os display reset over SSH, or use Back to the monitor's own mode in the web panel.
The VM has no sound
- Check the chosen output: the
akey in the session menu,vgpu-os soundor This computer › Sound in the web panel. Use the test tone to hear each output. - Sound may be turned off in that VM's settings, in OSX-REIMS.
- OpenCore's boot chime only exists in VMs created from OSX-REIMS 0.6.0 on.
The bridge does not turn on
The bridge needs a wired network port; Wi-Fi cannot be used. A VM set to Bridge does not start while the bridge is off: turn it on in Maintenance › VM network (or Maintenance › VM network in the web panel), or change the VM's network to NAT.
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 --splashExplains 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:
- Press Esc while the computer boots (the menu also comes back on its own after a failed boot).
- Choose Advanced options for vGPU OS GNU/Linux → vGPU OS rescue console.
- The rescue console is the Debian underneath the appliance. Type
vgpu-os diagnosticsfor the full report, orexitto 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.