OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
wayland-compat low very-common DISPUTE

Cursor reverts to the ugly X11 arrow (or vanishes) inside Steam, games and Java apps

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

Most of this record holds up. The ~/.icons/default/index.theme + Inherits= mechanism is documented verbatim at https://wiki.archlinux.org/title/Cursor_themes ("The default cursor theme is in the usual theme locations: ~/.local/share/icons/default/, ~/.icons/default/, /usr/share/icons/default/" and the Inheritance subsection). adwaita-cursors 50.0-1 exists in extra and ships usr/share/icons/Adwaita/cursors/. The gsettings and dconf commands are lifted from the hyprcursor wiki page, cursor:sync_gsettings_theme really does default to true and cursor:enable_hyprcursor to true (config-options.md), and the FAQ confirms "My cursor is a Hyprland icon? This means you have no hyprcursor theme installed, and Hyprland failed to find an XCursor theme as well." I also checked whether hyprctl setcursor Adwaita 24 would fail on an XCursor-only theme, since the wiki still claims "since 0.37.0, this only accepts hyprcursor themes". It does not fail: CCursorManager::changeTheme() in src/pointer/cursor/CursorManager.cpp logs "Hyprcursor failed loading theme, falling back to XCursor" and calls m_xcursor->loadTheme(name, ...), so step 5 is fine as written. Two things are wrong. (1) The danger note attributes /usr/share/icons/default/index.theme to "adwaita-cursors, xcursor-themes or your theme package". It is owned by neither: pacman -Qo /usr/share/icons/default/index.theme on this Omarchy 4 box returns default-cursors 3-1, and the Arch file lists confirm adwaita-cursors ships only usr/share/icons/Adwaita/ while xcursor-themes ships only handhelds/redglass/whiteglass. default-cursors is a dependency of both libxcursor and wayland, so it is present on every install, and its index.theme already reads Inherits=Adwaita, which is useful context the record omits: the fallback chain is not empty on a stock system, so this record really applies to someone wanting a *different* theme. The warning itself (don't edit it, use ~/.icons) is correct. Only the attribution is fabricated. (2) Step 4 puts HYPRCURSOR_THEME/HYPRCURSOR_SIZE in ~/.config/uwsm/env, but the uwsm page it cites says the opposite: "use ~/.config/uwsm/env for theming, XCursor, NVIDIA and toolkit variables, and ~/.config/uwsm/env-hyprland for HYPR* and AQ_* variables." Also worth stating: Omarchy 4 already sets XCURSOR_SIZE and HYPRCURSOR_SIZE to 24 in /usr/share/omarchy/default/hypr/envs.lua, which is pacman-owned and must not be edited.

The cause above was rewritten on 2026-09-01 to match this note; the fix was corrected by the audit itself.
RISK

Do not edit /usr/share/icons/default/index.theme. That file is owned by a package (adwaita-cursors, xcursor-themes or your theme package) and pacman will silently revert your change on the next upgrade, or leave a .pacnew you never notice. Always use ~/.icons/default/index.theme, which nothing owns.

Symptom

The desktop has my chosen cursor, but the instant the pointer crosses into Steam, a Proton game, GIMP, or a Java tool (Ghidra, JetBrains, Burp) it turns into the plain black X11 arrow, or a huge white one, or nothing at all. Setting XCURSOR_THEME in my Hyprland config changed nothing. On a fresh install the cursor is the Hyprland logo.

Cause

Hyprland draws a server-side cursor for Wayland-native clients using hyprcursor (falling back to XCursor). XWayland clients draw their own client-side cursor through libXcursor, which resolves the theme name from XCURSOR_THEME *in the process's own environment* and, failing that, from the Inherits= line of the "default" theme: ~/.local/share/icons/default/index.theme, then ~/.icons/default/index.theme, then /usr/share/icons/default/index.theme. That last file is owned by the default-cursors package (a dependency of libxcursor and wayland, so it is always installed) and ships Inherits=Adwaita, which is why an unconfigured system usually lands on Adwaita rather than nothing. Env vars set with hl.env() only reach processes Hyprland launches after that line. Steam relaunched by its own updater, a game started by the Steam client, or anything started by a systemd user unit never sees them. Under uwsm, session-wide variables belong in ~/.config/uwsm/env rather than in hyprland.lua at all. The Hyprland-logo cursor is the separate case where no cursor theme resolves at all: hyprcursor is the format/library, not a theme.

Fix

  1. Install a real cursor theme and note its **directory** name (that is the name you use everywhere, not the pretty name):

sudo pacman -S --needed adwaita-cursors    # or an AUR theme such as bibata-cursor-theme
ls /usr/share/icons ~/.local/share/icons ~/.icons 2>/dev/null

Note that default-cursors is already installed on every Arch/Omarchy system (it is a dependency of libxcursor and wayland) and it ships /usr/share/icons/default/index.theme containing Inherits=Adwaita. So the XCursor fallback chain is normally *not* empty. If you are seeing the Hyprland-logo cursor, that package or the Adwaita cursors are genuinely missing. If you are seeing plain black X11 arrows, the chain is resolving to something you did not choose and the rest of this fix redirects it.

  1. Set the libXcursor fallback so XWayland clients find your theme with no environment at all. Use the **user** path, which takes precedence over the system one:

mkdir -p ~/.icons/default
cat > ~/.icons/default/index.theme <<'EOF'
[Icon Theme]
Inherits=Adwaita
EOF

(Substitute your theme's directory name for Adwaita.)

  1. Set it for GTK/CSD clients through gsettings (Hyprland's cursor:sync_gsettings_theme is true by default and will keep these in step):

gsettings set org.gnome.desktop.interface cursor-theme 'Adwaita'
gsettings set org.gnome.desktop.interface cursor-size 24

If gsettings schemas are unavailable: dconf write /org/gnome/desktop/interface/cursor-theme "'Adwaita'"

  1. Set it for the compositor and for anything it launches. Omarchy 4 runs the session under uwsm, and the Hyprland wiki explicitly says uwsm users should not put theming/xcursor vars in hyprland.lua. It also splits them across two files: XCursor and toolkit vars in ~/.config/uwsm/env, HYPR* vars in ~/.config/uwsm/env-hyprland:

# ~/.config/uwsm/env
export XCURSOR_THEME=Adwaita
export XCURSOR_SIZE=24

# ~/.config/uwsm/env-hyprland
export HYPRCURSOR_THEME=Adwaita
export HYPRCURSOR_SIZE=24

Omarchy also sources ~/.config/uwsm/env.d/*, which is the tidier place if you keep several drop-ins. Do **not** edit /usr/share/omarchy/default/hypr/envs.lua, which already sets XCURSOR_SIZE and HYPRCURSOR_SIZE to 24. It is pacman-owned and your change would be reverted on the next omarchy update.

On a non-uwsm session the equivalent is in ~/.config/hypr/hyprland.lua:


hl.env("XCURSOR_THEME", "Adwaita")
hl.env("XCURSOR_SIZE", "24")
hl.env("HYPRCURSOR_THEME", "Adwaita")
hl.env("HYPRCURSOR_SIZE", "24")
  1. Apply to the running session without logging out:

hyprctl setcursor Adwaita 24

The wiki still says setcursor takes hyprcursor themes only. That is stale. Hyprland falls back to loading the same name as an XCursor theme if no hyprcursor theme matches. Add the call to your autostart so it survives a restart:


hl.on("hyprland.start", function()
  hl.exec_cmd("hyprctl setcursor Adwaita 24")
end)

This only affects server-side cursors, so it fixes Wayland-native clients immediately. XWayland clients still need steps 2 and 4.

  1. Log out and back in, then relaunch Steam/the game so it inherits the new environment.

If a theme ships only one bitmap size, XWayland may still scale it up into a giant arrow. That is a property of the theme, not your config. Themes that ship 24/32/48 variants (Adwaita, Bibata) do not have this problem.

Verify

hyprctl getoption cursor:enable_hyprcursor and hover over an XWayland window. hyprctl clients | grep -B2 -A6 xwayland confirms which clients are on the X side. Launch xterm or xeyes and check the cursor matches the desktop. echo $XCURSOR_THEME inside a terminal started from the launcher (not from an old shell) should print your theme.

Sources

xwayland-apps-wrong-cursor-theme