Documentation · Help
Troubleshooting
Use doctor, understand the most common messages and ask for help with the right log.
This documentation covers OSX-REIMS 0.6.0, alpha software. Commands and options may change between versions; when in doubt, check osx-reims --help on the installed version.
Start with doctor
osx-reims doctorIn the console, the same check is under Maintenance › Check this computer.
doctor checks the system, the GPU, KVM access, Reims vGPU and the OSX-REIMS files. It changes nothing, asks for no password and does not use the internet. Each check shows as OK, warning or failure, with a hint on how to fix it. At the end, it shows the totals and the path of its log.
To also check the connection to GitHub and to Rust's servers, which setup uses:
osx-reims doctor --onlineCommon doctor results
| Check | What to do |
|---|---|
| Processor: virtualization off or not supported | Enable Intel VT-x or AMD-V in the BIOS/UEFI |
KVM device: /dev/kvm is missing |
Enable virtualization in the BIOS/UEFI and restart the computer |
| Vulkan GPU: no GPU found or software rendering only | Install the GPU driver with Vulkan support |
Render node: no /dev/dri/renderD* |
Install the GPU driver |
| User groups: saved, but not active in this session yet | Log out and log back in, or restart the computer |
| KVM options: saved, but not in effect yet | Restart the computer |
| License: not accepted on this computer | Run osx-reims setup and accept the license |
| Local changes: changed files in Reims vGPU | setup does not update Reims vGPU while /opt/reims-vgpu has local changes |
| Free space: little space for VMs | Free up space: each macOS VM uses tens of GB |
| Nested VMs: not available | Intel computers only, with nested virtualization on in KVM; the VMs start without it |
VM GPU: no GPU has VK_EXT_external_memory_host |
No GPU on this computer can run VMs. On NVIDIA, install NVIDIA's full driver; on the others, update the Vulkan driver. See Requirements |
VM memory: a GPU without VK_EXT_external_memory_host |
A warning: that GPU cannot run VMs; the VMs use another one |
Memory maps: vm.max_map_count below what is needed |
Run osx-reims setup |
GPU memory access: no access to /dev/udmabuf (AMD GPUs) |
Follow the hint: sudo modprobe udmabuf, log out and back in, or osx-reims setup |
| Large GPU buffers: the AMD driver does not take large buffers | Update Mesa to version 26 or newer; without it, macOS can stop at its first accelerated screen |
| Build toolchain: Rust, clang or another build tool is missing | Run osx-reims setup: update-reims and rebuild-reims need it |
| VM network: VMs set to the bridge, with no bridge ready | Run osx-reims network bridge on, or set those VMs to NAT |
| VM GPU, GPU per VM, Sound, Backups | Informational: the GPU the VMs run on here, the VMs with a choice of their own, the sound server and the backups |
| Autostart | Informational: which VM opens by itself, and whether the computer logs in automatically |
| Serial number generator or license text missing | Reinstall OSX-REIMS |
| Packages, Reims vGPU, QEMU-Reims, boot program or folders | Run osx-reims setup |
When the hint says Run: osx-reims setup, running setup again is safe: it only redoes what is missing.
Common messages
"The environment is not ready"
The console shows this notice on first use or after an OSX-REIMS update, with the reason right below it, such as the license not accepted or setup not run yet. Press S to run setup.
"Virtualization (KVM) is not available in this session yet"
setup added your user to the kvm, render and video groups, but the change only applies to a new session. Log out and log back in, or restart the computer.
"Virtualization (KVM) is not available on this computer"
Hardware virtualization is off or not supported. Enable Intel VT-x or AMD-V in the BIOS/UEFI and restart.
"The OSX-REIMS license has not been accepted on this computer"
Run osx-reims setup and accept the license. This also happens when a new OSX-REIMS version brings a new license text.
"The VM boot program is outdated"
Usually shows up after installing a new OSX-REIMS version. Run osx-reims setup. The message "This version of OSX-REIMS does not match the VM boot program" has the same fix.
"Reims vGPU was changed outside setup"
Reims vGPU in /opt/reims-vgpu is not at the commit setup built. The VM may still start; if it fails, run osx-reims setup.
"Shut down all VMs first"
update-reims only runs with every VM shut down. Shut them down from macOS and try again.
"A VM is being created right now and is using the cache"
The cache cannot be cleaned while a VM is being created. Wait for the creation to finish and try again.
"macOS has not shut down yet"
There may be a confirmation in the VM window or an app preventing the shutdown. Check the VM window, then choose to wait longer, force the VM off or cancel.
The VM window does not open
This happened up to version 0.3.1 on desktops that do not run Wayland: Linux Mint's Cinnamon, MATE and Xfce sessions, and other X11 sessions. The VM ran with no window and nothing said why. In 0.4.0 the default is the server your session runs; if you need to, pick x11 in the settings menu (C › D) or start with osx-reims start <VM> --x11. See VM settings.
"This version of OSX-REIMS needs the new Reims vGPU"
It shows when a VM is started right after 0.6.0 was installed over an earlier version: the Reims vGPU on the computer is still the one from before the rewrite. With all VMs shut down, run osx-reims update-reims --tested. See The rewritten Reims vGPU.
The VM closes right after it opens, on an NVIDIA GPU
The start log (/opt/osx-reims/logs/latest.log) has Vulkan failure -3: the driver lacks the libcuda.so.1 library, which NVIDIA's Vulkan needs for Reims vGPU. Install NVIDIA's full driver (sudo ubuntu-drivers install, or the nvidia-driver-<version> package), restart the computer and start the VM again. On a VM with the automatic GPU, the same problem makes the VM run on another GPU.
The GPU is missing from the GPU list, or "no GPU here has VK_EXT_external_memory_host"
The GPU's Vulkan driver lacks the VK_EXT_external_memory_host extension, which Reims vGPU needs. That is the case of NVIDIA on the open nouveau driver (NVK). Such a GPU is not offered in the menu; when the automatic choice would land on it, start uses the best GPU that has the extension and says which one it passed over. With no such GPU at all, start refuses. Install NVIDIA's full driver, or update the GPU's Vulkan driver.
The VM window is black on an NVIDIA GPU
macOS runs behind a black window when Reims vGPU was built without OSX-REIMS' fixes — setup's log has building without it. It happens when following the latest version or a chosen commit. Go back to the tested version with osx-reims update-reims --tested. See Reims vGPU version.
macOS stops at the welcome screen, grey, or restarts in a loop
Up to 0.4.1, this happened on computers whose only GPU is an Intel or AMD integrated one, and OSX-REIMS worked around it with the GPU memory setting. On the rewritten Reims vGPU, the VM's memory always reaches the GPU the same way, and the setting is gone.
On an AMD GPU with a Mesa older than 26, the VM can stop at macOS's first accelerated screen (the setup assistant, after the installation). doctor warns about that case (Large GPU buffers): update Mesa. Ubuntu 26.04 already has a Mesa that works.
The keyboard does not reach macOS, or does not come back to Ubuntu
Click the VM window to give macOS the keyboard; Ctrl+Alt+Super, pressed together, give the keyboard back to Ubuntu (up to 0.4.1, it was Ctrl+Alt+Esc). The window's title says which state it is in.
GNOME asks about keyboard shortcuts every time
The VM window asks the desktop for the shortcuts macOS needs (Cmd, Alt+Tab, the Super combinations). On Wayland, GNOME confirms that request with a dialog every time the VM takes the keyboard, and never stores the answer. Starting the VM on X11 (C › D, or --x11) grants the same request without asking.
The VM powered off when its window was closed
Closing the VM window powers the VM off at once, like pulling its plug: anything unsaved is lost. Shut macOS down from its Apple menu, or with osx-reims stop.
"VM … is set to the bridge, which is not ready"
The VM is set to the bridged network, and there is no bridge on this computer. Turn the bridge on in Maintenance › VM network (or osx-reims network bridge on), or set the VM to NAT in C › N. The VM is never moved to NAT by itself. The bridge needs a wired network port; Wi-Fi will not do. See Network.
The VM has no sound
Check that the VM's sound is on (C › H) and that the summary's Audio line does not say there is no sound server: with no PipeWire or PulseAudio in the session, the VM starts silent. The speakers are the ones chosen in Ubuntu's sound settings. OpenCore's boot chime only exists in VMs created from 0.6.0 on.
"The GPU set for this VM … is not on this computer"
The GPU chosen for the VM is not on the computer when it starts — a VM folder brought from another computer, or an integrated GPU the motherboard switches off. The VM starts on the automatic GPU, the choice stays saved for when that GPU is back, and C › U picks another one.
The VM with autostart did not open
OSX-REIMS does not leave the failure hidden: a notification and a terminal window say why and open the console. To see the situation:
osx-reims autostart statusRemember that only one VM can have autostart, that it must already have macOS installed, and that the VM opens after you log in to the session — to go from turning the computer on to macOS, Ubuntu's automatic login has to be on as well. See VM settings.
The VMs stopped starting after a system update
An Ubuntu update can move libraries under a Reims vGPU build that was already made. With every VM shut down, build it again from scratch:
osx-reims rebuild-reimsIn the console the same thing is Maintenance › Rebuild Reims vGPU. Nothing is downloaded and the version does not change; the current build is only removed once the new one passes the checks. See Reims vGPU version.
"No osx-reims_*.deb was found in your Downloads or Desktop folder"
osx-reims update installs the package you already downloaded and downloads nothing. Download the new version's .deb with the Gerar meu link de download button in the #osx-reims Discord channel and run the command again, or name the file: osx-reims update <file>.deb. See Updating and removing.
The package fails the hash check
The file has the published version, but its SHA-256 is not the one that was published, so it is not installed. Download the file again with the Gerar meu link de download button in the #osx-reims channel.
The VM does not start after switching to the latest Reims vGPU
Go back to the tested version:
osx-reims update-reims --tested"Faulty (incomplete disk)" or "Faulty (no base disk)"
The VM disk is incomplete or its base disk is missing. Do not delete the VM before asking for help: share the log of its last run.
Importing a VM fails
The import messages and what to do about each one are in Importing a VM.
Logs
Every action writes a log to /opt/osx-reims/logs/, with the action, date and time in its name, such as osx-reims-start-20260914-213000.log. The latest one is also available as latest.log, and the 100 most recent are kept. In the console, View logs lists and opens them.
If your user cannot write to that folder, the log goes to ~/.local/state/osx-reims/logs/, and the screen says so.
For a more detailed log, repeat the action with --debug.
Asking for help
Important
OSX-REIMS has no technical support and is provided without warranty. The #osx-reims-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.
- Run
osx-reims doctorand note the log path shown at the end. - Find the log of the run with the problem, in View logs or in
/opt/osx-reims/logs/. - Share both logs in the #osx-reims-chat channel of the members' Discord, saying what you did and what happened, so other members can look into it.
Logs contain no VM serial numbers, MLB, UUID or ROM, and the doctor log contains no VM identity data at all. Sharing logs in the Universo Hackintosh support channels is allowed by the license.
Intact installed files
dpkg --verify osx-reimsNo output means the installed files are intact. If it lists changed files, install the package again.