Fixing Missing Dock Icons (startupwmclass)

Occasionally an app shows the right icon in the GNOME Applications menu, but once launched, the Dock displays a generic icon instead. That happens when GNOME can't match the running window to the app's .desktop file — usually because the window's WM_CLASS doesn't line up with what GNOME expects. Adding the correct StartupWMClass value fixes the mapping.

Find the Running App's Wm_class

Open GNOME's built-in debugger:

Alt + F2  →  type "lg"  →  Enter

This opens Looking Glass. Go to the Windows tab, find the app in the list, and copy the value shown next to wmclass — for example:

wmclass: qpdfview.local.qpdfview

Add it to the .desktop File

nvim ~/.local/share/applications/appname.desktop

Add this line inside the [Desktop Entry] section:

StartupWMClass=<wmclass>

Example:

[Desktop Entry]
Name=qpdfview
Exec=qpdfview
Icon=qpdfview
StartupWMClass=qpdfview.local.qpdfview

Update the Desktop Database and Re-log

update-desktop-database ~/.local/share/applications

Log out and back in for GNOME to pick up the change.

Result

GNOME now correctly matches the running window to its .desktop file, and the Dock shows the proper icon instead of a generic placeholder.

Why this happens: GNOME identifies running applications by a window's WM_CLASS (or app ID). If that value doesn't match anything in the .desktop file, the app is effectively "untracked" from the Dock's point of view. This is especially common with Qt applications, and can also show up when using a custom icon theme. It works the same way on both Wayland and X11.