Document the Wayland icon-cache-needs-relogin gotcha #45

Merged
jknapp merged 1 commits from docs/wayland-icon-cache-note into main 2026-08-27 23:15:01 +00:00
Owner

A user hit this right after installing the new Arch/CachyOS package: icon missing in the app menu, taskbar, and window titlebar alike, with nothing in the app's own log. Confirmed via a real Arch container that the packaging is correct (icons at all four sizes, .desktop file, and the icon-theme cache all install and rebuild correctly via pacman's hooks). The actual cause is a GNOME/KDE Wayland session caching its installed-app/icon list in memory at shell startup, with no live-reload path on Wayland the way X11 had (soft shell restart) — logging out and back in fixed it. Adds a short Troubleshooting entry so the next person hitting this doesn't have to rediscover it.

A user hit this right after installing the new Arch/CachyOS package: icon missing in the app menu, taskbar, and window titlebar alike, with nothing in the app's own log. Confirmed via a real Arch container that the packaging is correct (icons at all four sizes, `.desktop` file, and the icon-theme cache all install and rebuild correctly via pacman's hooks). The actual cause is a GNOME/KDE Wayland session caching its installed-app/icon list in memory at shell startup, with no live-reload path on Wayland the way X11 had (soft shell restart) — logging out and back in fixed it. Adds a short Troubleshooting entry so the next person hitting this doesn't have to rediscover it.
jknapp added 1 commit 2026-08-27 22:53:30 +00:00
Document the Wayland icon-cache-needs-relogin gotcha
Secret Scan / scan (push) Successful in 4s
Secret Scan / scan (pull_request) Successful in 4s
6cc48b3266
A user hit this after installing the new Arch/CachyOS package (triple-c#34):
icon missing in the app menu, taskbar, and titlebar alike, with no error
in the app's own log. Root cause has nothing to do with the app or its
packaging — GNOME/KDE cache the installed-app list and resolved icons in
the shell process's memory at startup, and Wayland has no equivalent to
X11's soft shell-restart trick to force a live reload. Logging out and
back in fixed it for them.
jknapp merged commit 88d6bed6db into main 2026-08-27 23:15:01 +00:00
jknapp deleted branch docs/wayland-icon-cache-note 2026-08-27 23:15:01 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: CyberCoveLLC/Triple-C#45