Skip to content
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.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 --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 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 the nvidia driver, 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 provision to 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-user and 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 a key in the session menu, vgpu-os sound or 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 --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.