Omarchy Troubleshooting for Black Screens, Network, and Keys

Diagnose Omarchy boot, black screen, networking, display, audio, input, and shortcut problems in a recoverable order.

Troubleshooting is not typing the most commands as quickly as possible. Preserve evidence and narrow scope. Record the last known-good time, recent updates or configuration changes, and whether the issue reproduces consistently.

Establish the scope

Symptom	First question
One frozen app	Do other windows, terminals, and input still work?
Shortcut fails	Do the physical key, current layout, and built-in hotkey table agree?
No network	Is only DNS failing, or is there no link at all?
Black screen	Can you reach a TTY, is there a signal, and did graphics/display config just change?
Cannot boot	Does UEFI show the entry, does storage unlock, and at which stage does error appear?

Preserve evidence

Photograph or copy the complete error and record time, hardware, and version. Logs may contain usernames, hostnames, IPs, Wi-Fi names, or tokens; redact before publishing. Do not provide only the last line, and avoid repeated restarts before collecting evidence.

Test one hypothesis at a time

From lower to higher risk:

reproduce and establish scope;
undo the latest reversible user configuration;
use system-provided diagnostics and help;
read current official documentation and known issues;
restart the affected app or session after preserving logs;
change system packages or restore a snapshot only with a clear recovery path.

Common mistakes

Immediate reinstall: destroys evidence without proving hardware or configuration is fixed;
copying an old command: versions, package names, and paths change;
changing many things: even success does not identify the remedy;
treating snapshot as backup: both can disappear with one disk;
posting secrets: remove cookies, tokens, keys, and private paths.

Black screen and displays

Check cable, input source, and another display before software changes. Then determine whether a TTY or boot log is reachable. For hybrid graphics or external screens, record GPU, driver, connector, and refresh rate. Do not repeatedly overwrite display configuration while unable to see the result.

Networking

Test link, IP, gateway, DNS, and one website separately. A browser failure does not prove Wi-Fi is down; VPN, proxy, system time, and DNS can look similar.

Asking for help

Provide version, hardware, reproduction, expected and actual results, a complete redacted error, and checks already completed. Search the official Troubleshooting and FAQ manual before posting a minimal report.