Stuck at a TTY, or cannot switch to a TTY on Omarchy

A TTY is the plain text console behind the desktop. On Omarchy it is both a symptom (you booted and landed there instead of on the desktop) and the main repair tool (the desktop is broken and you need a shell). This page covers both, on 4.0.0 through 4.0.4, with the 3.x differences noted.

The fix

1. Get to a console. Press Ctrl+Alt+F2 or Ctrl+Alt+F3; any of F2 through F6 will do. VT1 is not free: SDDM’s greeter and your Hyprland session both sit there. You can see it in SDDM’s own log, which prints Jumping to VT 1 when it restarts a greeter, and in omarchy-debug output, which reports vt 1 for the desktop. Omarchy ships no logind override for the auto-spawned consoles, so Arch’s default login prompts on VT2 through VT6 are what you get. Ctrl+Alt+F1 returns you to the session.

At the login: prompt use your Linux username and its password. Not the LUKS passphrase, which the initramfs asks for once during early boot.

2. Find out what is missing. From the console:

systemctl status sddm
journalctl -b -u sddm
journalctl --user -b -u wayland-wm-env@hyprland.desktop.service
journalctl --user -b -u wayland-wm@hyprland.desktop.service
journalctl -b -t omarchy-shell

Omarchy starts Hyprland through uwsm on both 3.x and 4.x. The session entry is identical in v3.8.4 and v4.0.4: Exec=uwsm start -g -1 -e -D Hyprland hyprland.desktop. That produces two user units, the environment preloader and the compositor itself, and that first unit is where most silent failures live.

3. Check the uwsm environment first. If the greeter takes your password, flashes, and returns to the greeter while the TTY works fine, this is almost always it. uwsm sources ~/.profile and everything in ~/.config/uwsm/env.d/ before starting Hyprland, and any shell error aborts the session with nothing on screen.

Two confirmed shapes. In issue #8669 a Mac user on 4.0.1 had rustup’s unguarded . "$HOME/.cargo/env" as line 1 of ~/.profile with the file gone, and the journal showed wayland-wm-env@hyprland.desktop.service: Failed with result 'exit-code'. In issue #10700 on 4.0.2 a typo in an env.d fragment produced Env output mark ... not found in shell output and an endless return to the lock screen. Guard the profile line or delete it:

sed -i 's|^\. "\$HOME/.cargo/env"|[[ -r "$HOME/.cargo/env" ]] \&\& . "$HOME/.cargo/env"|' ~/.profile

For env.d, move the file out of the directory. Renaming it to .bak or .broken does not help, because uwsm loads every entry it finds there:

mkdir -p ~/broken-env && mv ~/.config/uwsm/env.d/99-bad ~/broken-env/

Note that a Snapper rollback will not fix either one. Both files live under /home, which snapshots of the root subvolume do not carry.

4. Start the session by hand. Still on the TTY:

uwsm start -g -1 -e -D Hyprland hyprland.desktop

If that fails or exits instantly, run the compositor bare so the crash lands on your screen instead of in a log:

Hyprland

That is how the VirtualBox diagnosis in discussion #7758 was done: Hyprland aborted with signal 6 right after Creating the AsyncResourceGatherer!, which put the fault at GPU and EGL init rather than anywhere in Omarchy.

If you use the start-hyprland wrapper, call it by absolute path as /usr/bin/start-hyprland, and check /usr/local/bin for leftovers. Issue #8319 reported failed to obtain hyprland version string (bad json) from a TTY on 4.0.0 with a stale /usr/local/bin/start-hyprland sitting ahead of the packaged one in PATH. Triage on that issue reproduced the message and pinned it down: start-hyprland runs Hyprland --version-json as a preflight, and the message means the Hyprland it found on PATH could not answer, typically a source-built copy under /usr/local whose libraries pacman has since upgraded underneath it. Neither hyprpm nor Omarchy writes there. Omarchy’s own session entry runs uwsm and never touches start-hyprland, but the SDDM greeter does: etc/sddm.conf.d/10-wayland.conf launches it as a bare start-hyprland, so the same shadow can take out the login screen as well as your typed command.

5. Check the config, then the shell. hyprctl configerrors reports a bad config. On 4.x that config is ~/.config/hypr/hyprland.lua and edits to a leftover hyprland.conf are ignored; on 3.x it is the .conf file. If Hyprland is up but there is no bar, omarchy-restart-shell works from a TTY, because it derives the Hyprland instance signature from the runtime directory and respawns the shell through the compositor.

6. Collect a log. Run omarchy-debug --no-sudo, which writes /tmp/omarchy-debug.log. From a TTY the router form omarchy debug works too. Inside a Hyprland terminal on 4.0.2 through 4.0.4 it answers Unknown Omarchy command: omarchy debug (issue #10258, open at the time of writing): the session puts /usr/share/omarchy/bin first on PATH and that directory carries no link to omarchy-debug, which the omarchy-settings package installs under /usr/bin only. The hyphenated script works from anywhere.

Verify it worked

systemctl --user status wayland-wm@hyprland.desktop.service
hyprctl monitors
hyprctl layers | grep omarchy-bar

The unit should be active, hyprctl monitors should list a real output rather than error out, and the omarchy-bar layer should be present. Then press Ctrl+Alt+F2 and Ctrl+Alt+F1 once each: a session that survives a round trip through a console is a session whose compositor is answering.

Why it happens

The greeter and the session share VT1, and everything else is queued behind that. When SDDM is asked to put a second greeter on the same VT, its helper cannot take the tty and the display dies with Greeter stopped. SDDM::Auth::HELPER_TTY_ERROR, which is what issue #11700 reports from a SwitchToGreeter D-Bus call on 4.0.3. Do not call it; start a second session from a spare TTY instead.

Landing on a console instead of the desktop means something in the chain exited: SDDM, the uwsm preloader, or Hyprland. The preloader case is silent by design, which is why it accounts for so many “wrong password” reports that turn out to be nothing of the sort. The Hyprland case is usually GPU init, as in the VirtualBox report, or a Hyprland binary on PATH that no longer matches its libraries, as in issue #8319.

The reverse problem, no console at all, has a different root. Under Wayland the compositor owns the keyboard on its VT and carries out the switch itself through the seat it holds from logind, so Ctrl+Alt+F<n> is a request to Hyprland rather than to the kernel console. A compositor that is wedged in a GPU or output operation never processes it. This also explains why a VT switch is such a reliable unsticker when the compositor is alive but confused: issue #11208 on 4.0.3 describes a lock screen that ignores the keyboard after resume until Ctrl+Alt+F3 and back forces a DRM and VT transition, after which typing works again.

If that did not work

If no function key reaches a console, you have three options left. SSH in from another machine, if you turned sshd on beforehand. Power cycle and pick an older snapshot in the Limine menu, covered in rollback with Snapper and Limine. Or boot the install media and chroot in.

If the console works but the desktop still will not start, the fault is downstream of this page. Go to black screen after login when Hyprland starts and nothing draws, Quickshell crashes or bar missing when Hyprland is running without a bar, and login loop or password not accepted when the greeter keeps coming back. NVIDIA machines that stopped booting after an update belong on the NVIDIA hardware page, and virtual machines on what breaks in a VM.

One honest gap: the issue tracker has plenty of reports of the console being used as a rescue shell, and several of sessions frozen hard enough that nothing responds, but very few that isolate why a specific machine refuses the VT switch. If yours does, the journal from the next boot is the only evidence worth filing.

Related

• Black screen after login
• Quickshell crashes or bar missing
• Login loop or password not accepted
• Lock screen will not unlock
• Rollback with Snapper and Limine
• Hyprland conf to Lua migration
• Omarchy manual: Troubleshooting