Omarchy Troubleshooting for Boot, Display, Network, Audio, and Login

Preserve evidence and establish scope before changing the system. Record the last known-good time, recent update or configuration change, and a stable reproduction. Test one hypothesis at a time. If the ISO writer or installer itself stopped before the first successful boot, use installation troubleshooting instead.

1. Capture a diagnostic baseline

Start with read-only commands:

date
uname -a
omarchy debug
systemctl --failed
journalctl -b -p warning..alert --no-pager

-b means the current boot. If the failure occurred during the previous boot, inspect:

journalctl -b -1 -p warning..alert --no-pager

Redact usernames, hostnames, IPs, Wi-Fi names, serial numbers, mount paths, and tokens before sharing. Do not provide only the last error line.

2. Broken boot or desktop after an update

1. Select Limine from the firmware boot menu.
2. Choose the snapshot dated before the update.
3. Confirm the failure is absent after booting that snapshot.
4. Click the restore notification or run:

omarchy-snapshot restore

If login works but shipped packages and defaults are broadly damaged, back up user changes and run:

omarchy reinstall

This returns to stable, reinstalls defaults, and resets Omarchy-managed configuration. It does not recover /home. Read snapshots and recovery for the full boundary.

3. Black screen, scaling, or external displays

Check cable, input source, and another display first. Press Ctrl + Alt + F2 to try a TTY. A working TTY proves the OS booted and points toward the graphical session or display configuration.

Collect graphics, driver, and monitor state:

lspci -k | rg -A3 'VGA|3D|Display'
hyprctl monitors all
journalctl -b | rg -i 'drm|gpu|nvidia|amdgpu|i915|hypr'

For globally oversized apps, the official guide points to ~/.config/hypr/monitors.lua. A 1x display can change:

local omarchy_gdk_scale = 2

to 1, then restart affected applications. Back up the file and do not change refresh rate, scale, and GPU settings simultaneously.

4. Wi-Fi or DNS

Test each layer instead of treating a browser failure as proof Wi-Fi is down:

nmcli device status
ip -brief address
ip route
ping -c 3 1.1.1.1
resolvectl query omarchy.org

• No interface or link: investigate radio state, hardware, or driver.
• Address but no default route: inspect the connection.
• IP ping works but DNS fails: inspect DNS, VPN/proxy, and system time.
• One site fails: do not reset the entire network.

For a transient failure, try Super + Space → Update → Hardware → Wi-Fi. Bluetooth, Audio, and Trackpad have separate restart entries.

5. Audio and Bluetooth

Use the speaker icon to verify the primary output and per-app volume. Inspect PipeWire/Pulse state:

wpctl status
systemctl --user --failed
journalctl --user -b | rg -i 'pipewire|wireplumber|bluez'

Some laptops receive automatic speaker tuning. Inspect or disable it with:

omarchy audio tuning status
omarchy audio tuning off

Prefer Update → Hardware → Audio/Bluetooth to reload one subsystem before rebooting the whole machine.

6. btop says Terminal size too small

The community reproduced an Omarchy 4.0.1 interaction in which increasing Foot's terminal font leaves the Super + Ctrl + T btop float with fewer than 80 columns by 24 rows. btop then refuses to render. The report remained an open issue on 2026-09-04, so its personal window rule is not an official universal fix.

Start with non-destructive checks:

1. Run btop inside a normal full-screen terminal.
2. If that works, the float geometry is more likely than a broken btop install.
3. Press Super + T on the hotkey-opened window to tile it, or temporarily reduce terminal font size.
4. Run stty size to see the actual row and column count.
5. Record display scale, terminal, and font size before reporting the problem.

Do not blindly copy a fixed 1100×740 rule. It may overflow a 720p or heavily scaled display. Reference: GitHub issue #8702.

7. Correct password rejected by login or sudo

Repeated failures trigger faillock. From the lock screen, press Ctrl + Alt + F2, log in as root, and reset only the actual affected user:

faillock --user your-username
faillock --reset --user your-username

Replace your-username. A failure at disk unlock is not faillock; these commands cannot reset a LUKS passphrase.

8. Ask for help effectively

Provide hardware, Omarchy version, reproduction, expected and actual result, recent changes, completed checks, and the complete redacted error. The official Discord has #omarchy-help; review omarchy debug for sensitive data before sharing.

Sources: Omarchy Troubleshooting and System Snapshots.