OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
omarchy-core critical occasional DISPUTE

Recover a black screen after an update migration rebuilt the initramfs

omarchyarchnvidiahyprlandwayland
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

The symptom is real but the fix edits the wrong files and would actively damage an Omarchy system. Verified in the repo: Omarchy does NOT manage /etc/mkinitcpio.conf directly: install/hardware/nvidia.sh writes /etc/mkinitcpio.conf.d/nvidia.conf containing MODULES+=(nvidia nvidia_modeset nvidia_uvm nvidia_drm) (append, not assign). Telling the user to set MODULES=(nvidia ...) in /etc/mkinitcpio.conf clobbers other hardware drop-ins (thunderbolt_module.conf, surface/apple keyboard drop-ins all use MODULES+=). The kms advice is also wrong: /etc/mkinitcpio.conf.d/omarchy_hooks.conf already drops kms automatically and CONDITIONALLY (only when nvidia_drm is early-loaded and NVIDIA owns every display), with a dedicated test at test/shell.d/nvidia-kms-hook-test.sh. Hand-editing HOOKS fights it. Worst of all, the cmdline check is wrong: install/hardware/nvidia.sh sets modesetting via /etc/modprobe.d/nvidia.conf (options nvidia_drm modeset=1), NOT the kernel cmdline, so cat /proc/cmdline | grep -i nvidia returns nothing on a perfectly healthy machine and will send users chasing a non-problem.

The cause above was not rewritten and may still contain the error described. The fix below is the corrected version.
RISK

Editing mkinitcpio.conf and rebuilding the boot image can make the system unbootable if the wrong hooks are removed. Keep an Arch live USB handy and do not delete the previous snapshot until the new boot is confirmed.

Symptom

After an omarchy update that ran a migration touching the boot image, the machine reboots into a black screen or a broken session, and the crash watcher reports:


failed to get hyprland version string (bad json)

Users report the update "looked fine" and only the reboot revealed the breakage.

Cause

An Omarchy migration script rebuilds the initramfs via limine-mkinitcpio. On NVIDIA systems that rebuild can drop the required modules (or the nouveau GSP firmware), so the proprietary driver never loads. Hyprland then cannot get GPU rendering and exits, and the watchdog's hyprctl version -j returns nothing parseable, hence the "bad json".

Fix

Boot the previous snapshot from the Limine menu, or get to a TTY with Ctrl + Alt + F2. Confirm the driver did not load:


lsmod | grep -i nvidia
journalctl -b -p err --no-pager | head -50

Do NOT edit /etc/mkinitcpio.conf. Omarchy configures NVIDIA entirely through drop-ins. Check that they still exist and are intact:


cat /etc/mkinitcpio.conf.d/nvidia.conf
# expect: MODULES+=(nvidia nvidia_modeset nvidia_uvm nvidia_drm)

cat /etc/modprobe.d/nvidia.conf
# expect: options nvidia_drm modeset=1

If the mkinitcpio drop-in is missing or was truncated, recreate it exactly as the installer does. Note the +=, which appends instead of wiping the other hardware drop-ins:


printf 'MODULES+=(nvidia nvidia_modeset nvidia_uvm nvidia_drm)\n' | sudo tee /etc/mkinitcpio.conf.d/nvidia.conf
printf 'options nvidia_drm modeset=1\n' | sudo tee /etc/modprobe.d/nvidia.conf

Leave the kms hook alone. Omarchy's /etc/mkinitcpio.conf.d/omarchy_hooks.conf removes it automatically, and only on systems where nvidia_drm is early-loaded and NVIDIA drives every display. Removing it by hand breaks hybrid-GPU laptops.

Rebuild the initramfs and the Limine entries in one step:


sudo limine-mkinitcpio
sudo reboot

Verify modesetting is actually on. It is set through modprobe.d, so it will NOT appear in /proc/cmdline. Check the module parameter instead:


cat /sys/module/nvidia_drm/parameters/modeset
# expect: Y

Verify

After reboot, lsmod | grep nvidia_drm shows the module loaded and hyprctl version -j returns valid JSON.

Sources

nvidia-initramfs-migration-breaks-boot