Troubleshooting

Start with doctor#

osx-reims doctor

In 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 --online

Common doctor results#

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 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#

1. Run osx-reims doctor and note the log path shown at the end.
2. Find the log of the run with the problem, in View logs or in /opt/osx-reims/logs/.
3. Share both logs in the #osx-reims channel of the members' Discord, saying what you did and what happened.

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-reims

No output means the installed files are intact. If it lists changed files, install the package again.