OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
omarchy-theming low common DISPUTE

Fix broken launcher icons and a ghost Alacritty entry after the Quattro upgrade

omarchyomarchy-4hyprlandwaylandlaptopdesktop
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Both defects are still present in omarchy 4.0.2-1 on this workstation. I read /usr/share/omarchy/bin/omarchy-upgrade-to-quattro lines 2169 to 2224 and confirmed the same content on the upstream quattro branch. The record's cause was imprecise in one way that changes the fix: the script does not move the legacy icon directory aside, it moves twenty specifically named stock PNGs out of it and then rmdirs the directory only if that emptied it, so a user's own PNGs are untouched and a dangling path can only be one of those twenty names. I also found a detail the record missed that strengthens it: the same script deletes ~/.local/share/applications/Alacritty.desktop in an earlier cleanup loop and then copies it back guarded on ! -f of the file it just deleted, so the guard always passes and the ghost entry is created on every upgrade rather than only sometimes. Cited issue 6883 was read in full, is OPEN, and supports every claim the record makes including the exact mv line and the QQuickImage log text. The larger correction is to the fix. omarchy-settings 4.0.2-1 ships 18 of the 20 legacy icons as themed icons under /usr/share/icons/hicolor/*/apps/, which I verified by find plus pacman -Qo (windows.png, basecamp.png, chatgpt.png and others are owned by omarchy-settings 4.0.2-1), so rewriting the entry to the icon name is durable while restoring PNGs into a directory Omarchy no longer maintains is not. Only GitHub.png and Battle.net.png have no packaged equivalent, which is also the correct scope for the danger note. I corrected the danger accordingly, since the old text claimed the backup was the only copy of everything. NOT exercised: this workstation has no icons.omarchy-upgrade-to-quattro.*.bak directory and no Alacritty.desktop, alacritty is not in PATH, and the dangling scan from the record prints nothing here, so this machine was never upgraded through that path and the symptom was not reproduced live. I did not run the upgrade script. Severity low and frequency common were left alone: the consequence is cosmetic plus one dead menu entry, and it hits anyone who upgraded rather than installed fresh.

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

GitHub.png and Battle.net.png exist nowhere else on Omarchy 4, so icons.omarchy-upgrade-to-quattro.*.bak is the only copy of those two. Do not delete that directory until every entry that referenced them has been restored or rewritten. The other eighteen names are shipped by omarchy-settings and can be recovered with pacman -S omarchy-settings at any time.

Symptom

After upgrading from Omarchy 3 to Quattro, custom launchers in the Apps menu have broken icons, and there is a dead Alacritty entry with a generic gear icon that launches nothing (even though alacritty is not installed). journalctl --user shows QML QQuickImage ... Cannot open: file:///home/<user>/.local/share/applications/icons/GitHub.png.

Cause

omarchy-upgrade-to-quattro does not move the legacy icon directory aside. It moves twenty *named* stock PNGs out of ~/.local/share/applications/icons into ~/.local/share/applications/icons.omarchy-upgrade-to-quattro.<timestamp>.bak with mv -f "$legacy_icons_dir/$icon" "$legacy_icons_backup/", then runs rmdir on both directories, which succeeds only if they are empty. Any PNG you put there yourself is left exactly where it was. Custom .desktop files survive the upgrade, so an entry whose Icon= is an absolute path to one of those twenty names is now dangling, and the Quickshell shell logs QML QQuickImage ... Cannot open: file:///home/<user>/.local/share/applications/icons/GitHub.png. The Alacritty entry is a second defect in the same script. The upgrade first deletes ~/.local/share/applications/Alacritty.desktop as part of a list of stale Omarchy 3 entries, then copies default/alacritty/Alacritty.desktop back guarded only on [[ ! -f $HOME/.local/share/applications/Alacritty.desktop ]], a test on the file it has just removed, so the guard always passes. There is no check that alacritty is installed, unlike omarchy-refresh-applications, which does guard on omarchy-cmd-present alacritty. The Apps menu lists the entry regardless of its TryExec=alacritty, and selecting it launches nothing.

Fix

**1. Find the dangling absolute icon paths.**


grep -h '^Icon=/' ~/.local/share/applications/*.desktop | sed 's/^Icon=//' \
  | while read -r p; do [[ -e $p ]] || echo "MISSING: $p"; done

**2. Point the entry at the packaged icon name, not at a restored file.**

omarchy-settings ships 18 of those 20 legacy icons as themed icons under /usr/share/icons/hicolor/*/apps/, lowercased with spaces turned into hyphens: basecamp, chatgpt, cliamp, disk-usage, docker, google-contacts, google-maps, google-messages, google-photos, hey, imv, retro-gaming, whatsapp, windows, x, youtube, zoom, and omarchy-discord for Discord. Rewriting the entry to the name survives future upgrades, because ~/.local/share/applications/icons is no longer a directory Omarchy maintains:


sed -i 's|^Icon=.*/applications/icons/windows\.png$|Icon=windows|' \
  ~/.local/share/applications/windows-vm.desktop

Confirm the name resolves before trusting it:


find /usr/share/icons -path '*/apps/*' -iname 'windows.*'

**3. Restore from the backup only for the two with no packaged equivalent.**

GitHub.png and Battle.net.png ship nowhere on Omarchy 4, so the .bak directory is the only copy of those:


ls -d ~/.local/share/applications/icons.omarchy-upgrade-to-quattro.*.bak
mkdir -p ~/.local/share/applications/icons
cp ~/.local/share/applications/icons.omarchy-upgrade-to-quattro.*.bak/GitHub.png \
   ~/.local/share/applications/icons/

If no .bak directory exists, the upgrade found none of the twenty names to move and your dangling path points at something you added yourself, which the upgrade never touched.

**4. Remove the ghost Alacritty entry.**


command -v alacritty >/dev/null || rm -f ~/.local/share/applications/Alacritty.desktop
update-desktop-database ~/.local/share/applications

The Apps menu's own remove action runs omarchy-remove-launcher-entry Alacritty Alacritty, which does the same delete plus the database refresh for a user owned entry.

**5. Refresh the menu.**

The shell watches ~/.local/share/applications, so the removed entry disappears and the icon index rebuilds on the next menu open with no restart. Only if an icon is still stale after reopening the menu:


omarchy restart shell

omarchy restart shell refuses to run while the session is locked.

Verify

The loop in step 1 prints no MISSING: lines. The Apps menu under Super+Space shows real icons for your custom launchers and no Alacritty entry. Reopening the menu adds no new QQuickImage Cannot open lines to journalctl --user -f.

Sources

app-menu-broken-icons-after-quattro-upgrade