Troubleshooting
The default desktop environment on a growing number of Linux distributions uses Wayland, which is currently only supported be the beta version of Cairo-Dock (3.5.99; see the Installation page) and only on a limited set of compositors (see here). If you are experiencing strange issues, it is worth checking if your are running a supported setup. To check if you are running Wayland, refer to the XDG_SESSION_TYPE environment variable, i.e. run the following in a terminal:
echo $XDG_SESSION_TYPE
Typically OpenGL is supported on most hardware from the past 10-15 years. Still, if you experience issues, especially glitches with rendering, it is worth trying to run the dock in a Cairo-only mode. This can be achieved by running Cairo-Dock from the terminal with the -c flag:
cairo-dock -c
or by selecting the "Cairo-Dock (Fallback Mode)" from the system menu, and then selecting "no" in the dialog. If the default setting is to run Cairo-Dock with OpenGL, it can also be changed by starting it with:
cairo-dock -A
and saving the new selection.
On X11, Cairo-Dock requires compositioning for proper functioning (without it, you will see a black rectangle around it). Most common window managers support this, but it might need to be specifically enabled in their settings. Some lightweight window managers (such as Openbox) do not, and you need to run a separate compositor, such as xcompmgr or picom.
While generally it's recommended to use the stable version, the beta version contains some additional bug fixes that could not be easily backported to the stable version. If you experience an issue with the stable version, it can be worth trying the beta to see if it's already fixed there.
Please check below first if your issue is already known / has a workaround. If not, please use the Github issues to report it. When reporting an issue, please try to include the following information:
- version of Cairo-Dock and how it was installed (from source, your distribution, PPA, etc.)
- the desktop environment and / or window manager or Wayland compositor you're running
- whether running without OpenGL (from a terminal, run
cairo-dock -c) helps
On a recent version of Cairo-Dock (3.5.99 or newer), many of this info is available by right clicking the dock, selecting "Cairo-Dock" (the topmost item) and "About" and then the "Technical info" tab -- just copy the text from there. On older versions, the "About" dialog only shows the version of Cairo-Dock (which is still useful). If you cannot run Cairo-Dock at all (it crashes on startup), then try to run it from a terminal and copy the information that gets printed out there.
This can happen if Cairo-Dock is started multiple times, maybe because multiple autostart methods are active. See here for common methods to start Cairo-Dock, and ensure that only one of them is used. Specifically, if using the desktop session provided with Cairo-Dock, then it should not be added to XDG or systemd autostart.
This is caused by the lack of compositioning on X11, see above.
If Cairo-Dock shows up in an unexpected position, this is most likely the consequence of running it on an unsupported Wayland compositor (or running an unsupported version). See here for more info. On X11, the dock can be freely moved by ALT + drag with the left mouse button, and the position should be remembered.
Support for HiDPI screens on X11 is incomplete, this can cause reduced quality rendering.
It is possible that the auto-hide feature is activated. Typically, Cairo-Dock can be recalled by moving the mouse to the edge of the screen where it would normally appear. Auto-hide can be disabled in the settings. It is also possible that the dock is hidden by an open window. Try moving any open window out of the way. You can configure the dock to appear always on top or reserve space for itself. You can also use the "ShowDock" DBus method to reveal a hidden dock, e.g. by running the following from a terminal:
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ShowDock int32:1
This should not happen and is likely a bug in your window manager / compositor. You can use the quick-hide feature to get rid of it (right click anywhere and it's in the "Cairo-Dock" submenu).
Finding the correct icon for some apps to show in the dock can be difficult. This problem can be especially relevant on Wayland (when using the beta), since on X11, there is a direct way for an app to provide an icon. If you experience this, please report an issue with the name of the app and the version of Cairo-Dock you're using, so we can try to improve the matching process. Also, you can set a custom icon (just right click on the app, point on its name and select "Set custom icon" or "Edit" if it is a launcher); see below on how to find a suitable icon.
If a launcher does not display a correct icon, or behaves strangely (especially after an update), it is recommended to remove it and recreate it by dragging it to the dock from the menu ("Applications Menu" plugin). If it still displays the wrong icon, you might need to manually set it (select "Edit" from the launcher's right click menu and use the "Image's name or path" setting).
If you use the "Set custom icon" setting for an app (or the "Image's name or path" setting for a launcher), you need to select an icon from the file system. By default, the /usr/share/icons folder will be selected. From here, navigate under hicolor/scalable/apps and you should look for an icon with the apps name (or a suitable one). Alternatively, you can look in any of the other subfolders under hicolor, which should have an apps subfolder as well. Some other locations that might work:
- Apps installed from source might put their icons under
/usr/local/share/icons/hicolor/, again underscalable/appsor one of the other subfolders. - Apps installed without administrator rights (e.g. Wine apps) could put their icons in your home directory, under
~/.local/share/icons/hicolor - Snap apps will put their icon under
/snap/[appname]/current/meta/gui(where[appname]is the name of the app)
This is likely #28 which is fixed in the latest stable version (3.5.1) and also in the beta (3.5.99). If updating to one of these versions does not help, please open a new issue.
This can happen if the ID reported by an app does not match what is expected based on its metadata (.desktop file). This can be a bug in the app or mean that it is incorrectly installed. More recent versions of Cairo-Dock, especially the beta (3.5.99) include some heuristics to work this around. This can be worked around by editing the launcher, expanding the "Extra parameters" (hidden by default) and entering a value for the "Class of the program". Typically, clicking on "Grab" and then on one of the app's open windows will work. Please also report the issue here so that we can look into adding a workaround.
