GNOME/Troubleshooting

Shell freezes

In the event of a shell freeze (which might be caused by certain appearance tweaks, malfunctioning extensions or perhaps a lack of available memory), restarting the shell by pressing Alt+F2 and then entering r may not be possible.

In this case, try switching to another TTY (Ctrl+Alt+F2) and entering the following command: pkill -HUP gnome-shell. It may take a few seconds before the shell successfully restarts. On X11, restarting the shell in this fashion should not log the user out, but it is a good idea to try and ensure that all work is saved anyway; on Wayland (currently the default), restarting the shell kills the whole session, so everything will be lost.

If this fails, the Xorg server will need to be restarted either by pkill X for console logins or by restarting gdm.service for GDM logins. Bear in mind that restarting the Xorg server will log the user out, so try to ensure that all work is saved before attempting this.

Incorrect application defaults

When installing applications for the first time you may find that GNOME has the wrong application associated to a certain protocols - for instance, easytag becomes the folder handler instead of GNOME Files.

For GNOME Files see the following page: GNOME Files#Files is no longer the default file manager.

To query the current associated application and recommended apps for pdfs in this case run:

$ xdg-mime query default application/pdf

To change the default app for pdfs to Document Viewer, run the following command:

$ xdg-mime default org.gnome.Evince.desktop application/pdf

For other applications, default handler settings are detailed on the following page: Default applications.

Optionally, you can install gnome-defaults-list^AUR. It will place your configuration file at /usr/share/applications/gnome-mimeapps.list.

Note:

There is another mime type association command. If the current associated app queried using xdg-mime query default <mime-type> is already correct, but still the wrong app is handling the type, try this:

Check the gio association by running: gio mime application/pdf
Change the association, if needed, using gio mime application/pdf org.gnome.Evince.desktop to Document Viewer

Tracker & Documents do not list any local files

In order for Tracker (and, therefore, Documents) to detect your local files, they must be stored in an XDG compliant directory (such as 'Documents' or 'Music'). For more information, see XDG user directories.

You can also configure Tracker to recursively search inside specific directories such as your home directory. These settings can be made using tracker-preferences.

GNOME Online Accounts settings page does not show properly

In some cases, due to interactions with Alacarte (menu editor), GNOME Online accounts settings page would not show. If that happens, "Restore System Configuration" in Alacarte can restore missing functions to gnome-control-center. (See https://bugzilla.redhat.com/show_bug.cgi?id=1520431.)

GNOME Online Accounts blank pop-up window when logging in

Some services require authentication to log in (Google, Microsoft, etc.), so in some situations (such as Nvidia drivers) the popup will go blank instead of redirecting to the login page. To solve this problem, temporarily disable WebKit Composite.

$ WEBKIT_DISABLE_COMPOSITING_MODE=1 gnome-control-center online-accounts

Cannot change settings in dconf-editor

When one cannot set settings in dconf, it is possible their dconf user settings are corrupt. In this case it is best to delete the user dconf files in ~/.config/dconf/user* and set the settings in dconf-editor after.

When an extension breaks the shell

When enabling shell extensions causes GNOME breakage, you should first remove the user-theme and auto-move-windows extensions from their installation directory.

The installation directory could be one of ~/.local/share/gnome‑shell/extensions, /usr/share/gnome‑shell/extensions or /usr/local/share/gnome‑shell/extensions. Removing these two extension-containing folders may fix the breakage. Otherwise, isolate the problem extension with trial‑and‑error.

Removing or adding an extension-containing folder to the aforementioned directories removes or adds the corresponding extension to your system. Details on GNOME Shell extensions are available at the GNOME web site.

If you have trouble with uninstalling an extension via extensions.gnome.org/local, then probably they have been installed as system-wide extensions with the gnome-shell-extensions package. Removing the package again obviously affects all user accounts.

Extensions do not work after GNOME 3 update

Note: Please bear in mind that whilst the methods below will allow you to try and activate an extension with an unsupported version of GNOME Shell, it is by no means a guarantee that the extension will work successfully. The most likely outcome of trying to activate such an extension is that GNOME Shell will crash and then restart.

Before trying the workarounds below, check if an update is available for the extension by visiting extensions.gnome.org/local.

If there is no update for your current GNOME version yet, use the following command to disable version validation for extensions:

$ gsettings set org.gnome.shell disable-extension-version-validation true

Alternatively, you could modify the extension itself, changing the supported shell version to satisfy the version validation. See the method below.

Locate the folder where your extensions are installed. It might be ~/.local/share/gnome-shell/extensions or /usr/share/gnome-shell/extensions.

Edit each occurrence of metadata.json which appears in each extension sub-folder.

Insert:	`"shell-version": ["3.x"]`
Instead of (for example):	`"shell-version": ["3.4"]`

"3.x" indicates the extension works with every shell version. If it breaks, you will know to change it back.

Keyboard shortcut do not work with only conky running

The GNOME shell keyboard shortcuts like Alt+F2, Alt+F1, and the media key shortcuts do not work if conky is the only program running. However, if another application like gedit is running, then the keyboard shortcuts work.

Solution: edit .conkyrc

own_window yes
own_window_transparent yes
own_window_argb_visual yes
own_window_type dock
own_window_class Conky
own_window_hints undecorated,below,sticky,skip_taskbar,skip_pager

Unable to apply stored configuration for monitors

If you encounter this message try to disable the xrandr gnome-settings-daemon plugin:

$ dconf write /org/gnome/settings-daemon/plugins/xrandr/active false

Consistent cursor theme

See Cursor themes#Desktop environments.

Windows cannot be modified with Alt-Key + mouse-button

In GNOME 3.6 and above, the mouse button modifier (the key that allows you to drag a window from a location other than the titlebar) is the Super key instead of the Alt key which was used in the past. The change was made in response to the following bug report.

To change the mouse button modifier back to the Alt key, execute the following:

$ gsettings set org.gnome.desktop.wm.preferences mouse-button-modifier '<Alt>'

Note: It is not possible to change this with System settings > Keyboard > Shortcuts

Slow loading of system icons/slow GDM login

Problems with the loading of system icons, such the ones in the title bar of Files, might be solved by executing the following command:

# gdk-pixbuf-query-loaders --update-cache

Running the aforementioned command may also fix repeated occurrences of the "Oh no! Something has gone wrong!" error screen and/or very slow loading and login with GDM as described in the following forum thread.

Artifacts when maximizing windows

Maximizing windows may cause artifacts as of GNOME 3.12.0 - see the following forum thread and bug report. A solution is detailed in the following section: #Tear-free video with Intel HD Graphics.

Tear-free video with Intel HD Graphics

DRI3

According to a bug report, DRI3 includes the buffer_age extension that allows GNOME Shell's Mutter compositor to sync windows to vblank in an efficient way. Since version 1:2.99.917+682+g4eaab17-1, DRI3 is enabled by default in xf86-video-intel [1].

Intel TearFree

Enabling the Xorg Intel TearFree option is a known workaround for tearing problems on Intel adapters. However, the way this option acts increases memory consumption and lowers performance, see the original bug report's final comment^{[dead link 2024-10-12 ⓘ]}.

Mutter tweaks

Note: This workaround has been reported to have side effects and may not fix tearing in all cases.

GNOME Shell's Mutter compositor has a tweak known to address tearing problems (see the original suggestion for this fix and its mention in the Freedesktop bug report^{[dead link 2024-10-12 ⓘ]}). To enable this tweak, append the following line to /etc/environment: CLUTTER_PAINT=disable-clipped-redraws:disable-culling. Then restart the Xorg server.

Disable fullscreen unredirect

GNOME Shell does by default unredirect fullscreen applications. This may result in tearing. You can disable this with the gnome shell extension gnome-shell-extension-disable-unredirect^AUR.

Window opens behind other windows when using multiple monitors

This is possibly a bug in GNOME Shell which causes new windows to open behind others. To fix this issue, one can run the following command:

$ gsettings set org.gnome.shell.overrides workspaces-only-on-primary false

Lock button fails to re-enable touchpad

Some laptops have a touchpad lock button that disables the touchpad so that users can type without worrying about touching the touchpad. Currently, it appears that although GNOME can lock the touchpad by pressing this button, it cannot unlock it. If the touchpad gets locked you can run the following to unlock it:

$ xinput set-prop "SynPS/2 Synaptics TouchPad" "Device Enabled" 1

GNOME Shell keyboard sources menu not visible

A menu showing the keyboard input sources (for example 'en' for an English keyboard layout) should be visible next to the status area containing icons for network, volume and power sources. If the keyboard sources menu is not visible, this is probably because you have configured your Xorg keyboard layout in a way which GNOME does not recognise.

To ensure that the menu is visible, remove any Xorg keyboard configuration you might have created and set the keyboard locale using localectl.

Upon running the command and then logging out, you should find that the keyboard input sources menu is visible in GDM and in the GNOME Shell desktop. See Input sources in GNOME for more information.

Mouse cursor missing

When using a separate window manager with gnome-settings-daemon, the mouse cursor may vanish. Run:

$ gsettings set org.gnome.settings-daemon.plugins.cursor active false

No restart button in session menu when screen is locked

If XScreenSaver is installed, ensure that it is not running at startup, see GNOME#Autostart.

PulseAudio system-wide causes delay in GNOME and GDM

If you are running PulseAudio in system-wide mode, the PulseAudio 7.0 upgrade breaks GDM and GNOME. See this forum post for more information.

GNOME crashes when trying to reorder applications in the GNOME Shell Dash

The dash is the "toolbar" that appears, by default, on the left when you click Activities. Applications can be reordered in the dash by dragging and dropping. If this fails, and/or causes GNOME to crash, try changing your icon theme.

No H264 Video in GNOME Video Player (Totem)

See Codecs and containers#No H264, mpg4 or Musepack (.mpc) in Totem Player.

No suspend on LID closure

GNOME defaults to this behaviour about suspension:

No external monitor attached, computer goes in suspension when LID closes.
External monitor attached, computer does not go in suspension when LID closes.

Currently gnome-tweaks is not able to modify the behaviour on the second case, when a monitor is connected to the computer. While it can inhibit suspension with no monitor attached.

Note: Behaviour on LID closure is controlled also by systemd. See Power management#ACPI events.

gnome-shell / gnome-session crashes on session startup

Sometimes gnome-session crashes immediately after login. This might be more visible on wayland and it might seem as if every second login attempt fails. The problem can be temporarily worked around by removing the files in ~/.config/gnome-session/saved-session. A more lasting work-around is to disable the session manager's auto-save-session feature:

$ gsettings set org.gnome.SessionManager auto-save-session false

Low OpenGL performance and stuttering

With proprietary NVIDIA driver

This bug is much likely the cause of it. You should revert 383ba566bd7c2a76d0856015a66e47caedef06b6 commit in mutter. Use ABS for this and add git revert -n 383ba566bd7c2a76d0856015a66e47caedef06b6 to the prepare() function in the PKGBUILD or simply install mutter-performance^AUR instead.

With free drivers

If video playback stutters (a bit), try GNOME on Xorg instead of Wayland.

GNOME Wayland session not available

GNOME Wayland does not support more than one GPU for output yet, falling back on GNOME X11.

If your displays are only connected to one of your video devices, add this to your system environment variables:

MUTTER_ALLOW_HYBRID_GPUS=1

gnome-control-center is empty and does not list any categories

Under alternative window managers (i3 for example), gnome-control-center starts as an empty window. You need to set the variable XDG_CURRENT_DESKTOP to GNOME to start it (either in a script or exporting the variable in ~/.profile).

export XDG_CURRENT_DESKTOP=GNOME
gnome-control-center &

GNOME freezes for a second after using a Function (Fn) key shortcut

This is a problem with the brazilian portuguese ABNT 2 keyboard. If you have the brazilian portuguese enabled, GNOME might experience this problem. To fix this issue and keep using this keyboard layout, un-map the scroll lock button by commenting this line at /usr/share/X11/xkb/symbols/br:

modifier_map Mod3   { Scroll_Lock };

And restart the session (log out and in).

Zoom in/out keyboard shortcuts do not work on some applications

Ctrl+Plus and Ctrl+Minus keyboard shortcuts for zoom in/out functions do not work out of the box on some GNOME applications, such as Files and GNOME Terminal.

In such cases, open up GNOME Tweaks (gnome-tweaks) and navigate to Keyboard & Mouse > Additional Layout Options button > Layout of numeric keypad. Change the Disabled value to Hexadecimal.

Printers configuration does not work in GNOME settings

CUPS and system-config-printer should be installed

Screen reader does not work

Install espeak-ng. Alternatively, festival can be used

GNOME Software does not show Arch Linux packages

packagekit integration is voluntarily disabled and considered unsupported.

Right click does not work in touchpad

In touchpads where the buttons are divided (e.g. buttonless touchpads), tapping with one finger on the right side - or any other place - of the touchpad can give you the behavior of the left button, when right button is expected.

As of GNOME 3.28, the default behavior of touchpads is a two-finger tap emulate the mouse's right button. This behavior can be changed in GNOME Tweaks (gnome-tweaks) by going in Keyboard & Mouse in the left-side menu and then Mouse Click Emulation option.

The following values are available for click method:

Fingers: default value, two-fingers top to emulate right click button (default)
Area: tap button-right for the right click behavior and button-middle for middle click
Disabled: no mouse click emulation

Alternatively, this behavior can be changed in the command-line interface using gsettings. For instance, to set areas click method:

$ gsettings set org.gnome.desktop.peripherals.touchpad click-method areas

Device Security setting panel erratic behavior

See GNOME#Device Security Settings.

Cursor size or theme issues on Wayland

This article or section is a candidate for merging with Wayland#Qt.

Notes: Looks like this issue is not specific to GNOME. (Discuss in Talk:GNOME/Troubleshooting)

The cursor settings might not be set for some Qt applications like Telegram[2][3]. This may result in cursors being of the wrong theme, size and not being able to resize the window.

Set the XCURSOR_THEME and XCURSOR_SIZE environment variables manually (e.g., XCURSOR_THEME=Adwaita, XCURSOR_PATH=/usr/share/icons or XCURSOR_SIZE=24).

You can also use inline getting of current system's cursor size:

$ XCURSOR_SIZE="$(gsettings get org.gnome.desktop.interface cursor-size)" _executable

If mentioned variables does not work on Wayland (for example in Telegram), try also adding QT_QPA_PLATFORM=xcb

Force software rendering of GNOME

If you experience problems with your GPU driver, you can force software rendering of the GNOME session with the following environment variables:

For Wayland session:

MESA_LOADER_DRIVER_OVERRIDE=kms_swrast

For X11 session:

LIBGL_ALWAYS_SOFTWARE=1