Unofficial community reference. Not affiliated with 37signals or the Omacom Foundation. Download Omarchy only from omarchy.org.
omarchylinux.org Unofficial field manual

Fixes

Paste your error into the search box, or browse by area. Every page says which Omarchy versions it applies to and who found the fix. Built against 6,605 upstream issues and 2,626 discussions.

Updates and package errors

Boot, login, and disk encryption

Shell, bar, menu, and keybindings (Quickshell)

  • attempt to index a nil value (global 'o') workaround 3.x
    Hyprland starts with no bindings, no monitors and a config-error banner after Quattro. Your hyprland.lua never loads Omarchy's helpers, so the global o is nil.
  • Clipboard history not working on Omarchy 4 workaround 4.0.0 and later
    Omarchy 4 clipboard history stops recording text when a capture.sh process wedges. Kill it to get capture back, and fix Super + V paste failures.
  • Custom keybindings stopped working after upgrading to Omarchy 4 workaround 4.0.0 and later
    Omarchy 4 Quattro stopped loading ~/.config/hypr/bindings.conf. Port your custom keybindings to bindings.lua with o.bind and hl.unbind, then reload Hyprland.
  • Fonts wrong or missing after an Omarchy update workaround 4.0.0 and later
    Wrong monospace font, tofu boxes, or broken emoji after an Omarchy 4 update. Reset fontconfig with omarchy font set, rebuild the font cache, fix leftovers.
  • GTK4 and libadwaita apps ignore the Omarchy theme workaround 3.x
    Nautilus and other GTK4/libadwaita apps stay Adwaita gray on Omarchy 4. Omarchy only sets light or dark, so generate a gtk.css palette with a template and hook.
  • Notifications not showing workaround 4.0.0 and later
    No notification toasts on Omarchy 4? Check do-not-disturb, find out which daemon owns org.freedesktop.Notifications, and test with notify-send.
  • Omarchy lock screen will not unlock workaround 3.x
    Omarchy lock screen rejects the right password or never shows a prompt. Reset the faillock counter, restart the shell from a TTY, and repair the lock PAM file.
  • Omarchy shell plugin fails to load or the bar disappears workaround 4.0.0 and later
    A third-party or cloned Omarchy shell plugin will not load, or installing one leaves no bar at all. How to find the failing plugin, validate it, and remove it.
  • Quickshell crashes or the Omarchy bar is missing workaround 4.0.0 and later
    The Omarchy 4 Quickshell bar vanished or omarchy-shell keeps crashing. Restart the shell, read its journal, reset a broken bar, fix a Qt ABI mismatch.
  • Screenshot shortcut not working workaround 3.x
    Print Screen does nothing, the picker never appears, or screen recording fails silently on Omarchy 4.x. How to find which part of the capture chain broke.
  • Walker launcher missing after update by-design 4.0.0 and later
    Omarchy 4 removed the Walker launcher. Super + Space now opens the Omarchy menu and Super + Alt + Space opens the apps-only launcher.
  • Where did Waybar go after the Omarchy 4 update? by-design 4.0.0 and later
    Omarchy 4 replaced Waybar with the Quickshell bar, so waybar, its config, and omarchy-refresh-waybar are all gone. Here is where each piece moved to.

Display, GPU, and scaling

Wi-Fi, Bluetooth, and networking

Audio

  • No sound from laptop speakers on Omarchy workaround 3.x
    Silent built-in speakers on Omarchy 4: restart PipeWire, install sof-firmware, drop the ASUS soft-mixer config, and read the CS35L56 amp firmware log.

Keyboard, touchpad, fingerprint, webcam

Apps

AI agents and dev tools

Gaming

  • Steam or Proton game crashes on launch workaround 3.x
    Steam and Proton games that die seconds after launch on Omarchy 4: the lib32 driver check, leftover SDL_VIDEODRIVER, and the gamescope launch option.

Installing

Other

  • Battery drains fast on Omarchy workaround 3.x
    Why an Omarchy laptop burns battery faster than Windows, what power management actually ships in 4.0.4, and the profile, screensaver, and hybrid GPU fixes.
  • Hibernate fails or hangs on Omarchy workaround 3.x
    Hibernate writes the image but never resumes, or hangs before power-off. Check the Btrfs swapfile offset, NVIDIA early KMS, and HibernateMode on Omarchy 4.
  • Laptop will not resume from suspend on Omarchy workaround 3.x
    Omarchy 4 laptop stuck black after suspend: tell a failed freeze from a kernel resume failure, then fix FUSE mounts, NVIDIA sleep services and kernel bugs.

Reported errors without a page yet

The most-reported topics upstream that we have not written up. Each link runs a GitHub search across the Omarchy issues so you can find the thread.

TopicIssuesOpenSearch
codex13831136upstream issues
nvidia1254655upstream issues
quickshell1105700upstream issues
plugin787484upstream issues
claude781482upstream issues
omarchy-update / omarchy update683278upstream issues
migration595355upstream issues
suspend579377upstream issues
theme566246upstream issues
chromium536273upstream issues
audio451275upstream issues
notification419237upstream issues
lock screen399232upstream issues
screenshot361171upstream issues
cursor313173upstream issues
bluetooth310179upstream issues
battery276142upstream issues
luks272160upstream issues
wifi267112upstream issues
tty243117upstream issues
waybar22921upstream issues
black screen21599upstream issues
sddm213131upstream issues
walker21210upstream issues
clipboard20597upstream issues
font203102upstream issues
fingerprint186110upstream issues
mise18498upstream issues
keyboard layout15361upstream issues
steam15066upstream issues
hibernate148100upstream issues
scaling14874upstream issues
polkit14680upstream issues
speaker12575upstream issues
docker12339upstream issues
Creating a snapshot failed / snapper11765upstream issues
monitors.lua11577upstream issues
hyprlock10833upstream issues
1password8641upstream issues
tailscale7843upstream issues

Questions people ask

Where do Omarchy users get support?
Officially in the Omacom Discord (#omarchy-help) and GitHub Discussions; GitHub issues are for verified bugs only. Those places are hard to search, so this site rewrites solved problems as one page per error, with credit and links back to the thread.
How do I find the error string?
Copy the exact text from the terminal, the update log, or the notification. On Omarchy 4 the update log lives under ~/.local/state/omarchy/ and omarchy update prints where it wrote it. Paste the string into the search box.
What if my error is not here?
Check the "reported errors without a page yet" list below: each links a GitHub search that finds the upstream threads. Then run omarchy debug and ask in the official Discord. If you solve it, tell us and it becomes a page.