Troubleshooting - Cairo-Dock/cairo-dock-core GitHub Wiki

General

X11 vs Wayland

The default desktop environment on a growing number of Linux distributions uses Wayland, which is currently only supported on the latest version of Cairo-Dock (3.6.0; 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.6.0), 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.

If you are using one of the Cairo-Dock desktop sessions, this may happen after an update to the latest beta (3.6.90). This is likely caused by having Cairo-Dock as part of XDG-based autostart and also started by systemd. The fix is to either delete ~/.config/autostart/cairo-dock.desktop (if you're not using Cairo-Dock in another session), or ensure that it contains the X-GNOME-HiddenUnderSystemd=true key. You can just replace it with the latest version, from {prefix}/share/applications/cairo-dock.desktop (with {prefix} being /usr if you installed from system packages, or likely /usr/local if you installed from source), e.g.

cp /usr/share/applications/cairo-dock.desktop ~/.config/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. On older versions (< 3.6.0) this can also happen on HiDPI screen (if a > 1 scale factor is used).

Too small or blurry icons / text

Support for HiDPI screens is available in the latest stable version (>= 3.6.0), so please report a new issue if this still happens.

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

How to set a custom icon for an app

Wrong or no 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 set a custom icon for a launcher

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 version 3.5.1 and above. 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 (>=3.6.0) include some heuristics to improve identifying apps. 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.

how to manually identify an app for a launcher

Apps are not matched to their launcher and no icons on Wayfire

Wayfire has a setting for how app-ids are reported to clients. This is available under the "Workarounds" tab in WCM as "Application ID mode" (or as app_id_mode in the [workarounds] section of the config file). On older versions of Cairo-Dock (< 3.6.95), you need to set this to "Stock", otherwise identifying apps will not work. On recent versions (>= 3.6.95), it is not required and setting it to "Full" is recommended, see also here.

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 (3.6.0), or adding the following command line option:

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

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 release (3.6.0). 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.

Launching apps fails or takes too long (D-Bus activatable case)

Clicking on a launcher, it animates, but nothing happens. This can be caused by some environment variables not set in your session. To workaround this, try opening a terminal (or using the "terminal" plugin if you're unable to open a terminal app as well) and running the following command:

dbus-update-activation-environment --systemd WAYLAND_DISPLAY DISPLAY XAUTHORITY

After this, try again; if this fixes the problem, you need to configure the command to run automatically after login, i.e. add it to your desktop environment's autostart configuration. E.g.

Wayfire: https://github.com/WayfireWM/wayfire/wiki/Tips-&-Tricks#gtk3-applications-slow-startup-or-desktop-files-not-opening
Sway: https://github.com/swaywm/sway/wiki#systemd-and-dbus-activation-environments
Labwc: should be setup automatically, but you can use edit its autostart configuration. See also https://labwc.github.io/getting-started.html

To help diagnosing this problem and as a possible workaround, Cairo-Dock now supports the following command-line arguments:

--disable-systemd Will not use systemd to launch apps (they will be started as a child process of Cairo-Dock). Note that this can result in accounting the resource use of any app launched to Cairo-Dock itself (see e.g. https://github.com/Cairo-Dock/cairo-dock-core/issues/51).
--disable-dbus-activation Do not use DBus activation to launch apps (normally this is preferred for apps that support it).
--force-gio-launch Do not use custom code to parse commands to launch, but rely on GLib / GIO functions to launch apps (implies --disable-systemd and incompatible with --disable-dbus-activation).

If any of these workarounds are necessary, please open a new issue and include the name of the app that fails to launch normally, your desktop environment, and whether systemd is active.

Launching some apps still fails (e.g. Zotero)

Some apps have "complicated" launchers that we currently cannot parse correctly. This is rare, but a prominent example used to be Zotero if installed according to their instructions for Linux. The problem for Zotero is fixed in the latest development version (3.6.97 and newer), but other apps using even more complicated commands may still run into problems. In these cases, please open a new issue.

For older Cairo-Dock versions, the workaround to run Zotero is to manually edit the launcher and specify the command to run: right click on the launcher, point to the item with the app's name, and select "Edit" from the submenu. Enter to command in the "Command to launch on click" field. In the specific case of Zotero, you will need to input the full path to the zotero executable (the same location where you symlinked the zotero.desktop file if you followed their installation guide).

Launchers with custom commands not working

See also here -- running shell commands was disabled for version 3.6.0 - 3.6.1. The issue is fixed in version 3.6.2 and the development version (3.6.96 and newer). You may still run into problems when using shell variables that are interpreted by systemd (if enabled) and not passed to the shell; this is fixed in the development version (3.6.97 and newer, see here) and a backport to the stable release is being considered. A workaround is to disable integration with systemd (--disable-systemd).