General

X11 vs Wayland

The default desktop environment on a growing number of Linux distributions uses Wayland, which is currently only supported on 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

OpenGL vs Cairo

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.

Compositioning manager

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.

Stable vs beta version

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.

Reporting issues

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.

Common issues

Two (or more) docks

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.

Black background

This is caused by the lack of compositioning on X11, see above.

Wrong / random position

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.

Too small or blurry icons / text

Support for HiDPI screens on X11 is incomplete, this can cause reduced quality rendering.

Cairo-Dock cannot start due to "undefined symbol" error

When trying to run the dock from a terminal the following (or a similar) message is displayed and it does not start:

/usr/local/bin/cairo-dock: symbol lookup error: /usr/local/bin/cairo-dock: undefined symbol: g_bForceWayland

This is typically caused by having multiple versions of Cairo-Dock installed and the shared libraries of one being picked up when trying to start it. To solve it:

• if you installed Cairo-Dock via your package manager (or from the PPA), it is recommended to remove it and reinstall
• if installing from source, you might need to set the LD_LIBRARY_PATH environment variable to contain the "lib" directory under the installation prefix (this should not be necessary for the latest beta anymore)
• in some cases, you might need to run sudo ldconfig after installing / updating from source In any case, it is recommended to only keep one version of the dock installed. Versions compiled from source should be uninstallable by running sudo make uninstall from the build directory.

The dock disappeared

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

The dock stays in front of fullscreen apps

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).

Missing / wrong icon for some apps

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.

Wrong or icon for a launcher

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).

How to find an app's icon

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 under scalable/apps or 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)

Unrelated apps are grouped together

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.

Apps are not matched to their launcher

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.

No themes are available

There has been a lot of theme packages contributed by users that help with customizing the look and feel of Cairo-Dock. These are however not distributed in the main repositories, but are downloaded on demand when you select the "Themes" panel among the settings. Recently, these were moved to a new location (actually to a Github repo here) which will make older versions of Cairo-Dock not find them. You can fix this by upgrading to the newest version (Git master), or adding the following command line option:

cairo-dock -S https://raw.githubusercontent.com/Cairo-Dock/glxdock-repository/refs/heads/main/themes

This change will be backported to the stable version (3.5) soon as well.

The weather applet is not working

The previous provider for the weather applet is not available anymore, so it will not work on older versions. It was recently changed and should work again on the latest beta / rc (3.5.99 available from git). However, you need to manually supply your coordinates (right click on its icon, point to "weather" and select "Edit"; select the "Configuration" tab and there should be an entry for latitude and longitude). You can figure out your approximate location using any online map (e.g. on OpenStreetMap and Google Maps, it is displayed in the address bar as you move the map, with the latitude first). An option to select location directly will be added in a later version. Note that there is also a bug which causes the location to reset when you change themes; this will be fixed in a later version as well.

Compilation error due to undeclared identifiers

Recent changes included moving headers that are generated by cmake out of the source tree of cairo-dock-core. This can mean that when you update (by git pull), the old and new generated headers conflict, leading to error messages such as:

src/cairo-dock.c: In function ‘main’:
src/cairo-dock.c:351:25: error: ‘CAIRO_DOCK_PLUGINS_GETTEXT_PACKAGE’ undeclared (first use in this function); did you mean ‘CAIRO_DOCK_GETTEXT_PACKAGE’?
  351 |         bindtextdomain (CAIRO_DOCK_PLUGINS_GETTEXT_PACKAGE, CAIRO_DOCK_PLUGINS_LOCALE_DIR);
      |                         ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      |                         CAIRO_DOCK_GETTEXT_PACKAGE
src/cairo-dock.c:351:25: note: each undeclared identifier is reported only once for each function it appears in
src/cairo-dock.c:351:61: error: ‘CAIRO_DOCK_PLUGINS_LOCALE_DIR’ undeclared (first use in this function); did you mean ‘CAIRO_DOCK_LOCALE_DIR’?
  351 |         bindtextdomain (CAIRO_DOCK_PLUGINS_GETTEXT_PACKAGE, CAIRO_DOCK_PLUGINS_LOCALE_DIR);
      |                                                             ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      |                                                             CAIRO_DOCK_LOCALE_DIR

This is caused by an outdated version of config.h being found by the compiler. To fix this, you need to delete the following files in the source tree:

src/config.h
src/gldit/gldi-config.h
src/gldit/gldi-module-config.h

The dock starts but shows an error about "No plug-ins were found."

When running from the terminal, you may also see error messages like the following:

warning :  (src/gldit/cairo-dock-module-manager.c:gldi_module_new_from_so_file:214)  
  this module ('.../lib/cairo-dock/libcd-Cairo-Penguin.so') was compiled for Cairo-Dock ABI version 20250213, but currently running Cairo-Dock with ABI version 20250629
  It will be ignored

Or messages about "symbols not found".

This typically results in the dock being almost unusable (things look weird, missing functionality, etc.), and is caused by an incomplete installation: plug-ins are either not installed, installed in a location where they cannot be found or an incompatible version of them is installed. How to fix this depends on how you installed Cairo-Dock:

• If you installed Cairo-Dock with your package manager: check if any updates are available for the plug-ins as well (e.g. sudo apt update followed by sudo apt upgrade on Debian / Ubuntu). If using our weekly PPA, it is possible that the core and plug-ins packages will go out of sync for a short time (since they are built and published automatically); this will typically resolve itself in a couple of hours, after which you can update. If the problem persist, please report a bug here.
• If you built Cairo-Dock from source: to get a functioning dock, you need to build and install both the core and the plug-ins packages. If you already installed the plug-ins, you may need to recompile and reinstall them after an update to core (run make and sudo make install in the build directory). You may also need to update them first (git pull). In rare cases, it is possible to end up with multiple versions of Cairo-Dock and / or the plug-ins being installed, or an installation in the wrong place (this can especially happen if using a custom prefix, or having a version installed from your package manager). When configuring the plug-ins with cmake, it is best to explicitly give the prefix where the core is installed with the -DCMAKE_PREFIX_PATH=[prefix] argument.