Troubleshooting

General issues

Getting backtraces

At first you need to review Gentoo documentation for ensuring affected packages are built with debugging symbols. After that, you need to install app-admin/abrt and enable and start the provided unit files to be run at boot time. This will let ABRT to catch any crashes that could occur in your system.

You can follow this steps if you want:

Create /etc/portage/env/debug.conf file with this contents:

CFLAGS="-march=native -pipe -O2 -ggdb"
CXXFLAGS="${CFLAGS}"
FEATURES="${FEATURES} splitdebug"

Create a /etc/portage/package.env file and specify there the package you want to get recompiled with options specified at debug.conf file, for example:

gnome-base/gnome-shell debug.conf

Recompile the packages that you need to get installed with debugging symbols.
Let ABRT catch the crashes. Once it catches them, either it will be automatically opened to let you process the backtraces or you will be able to get them manually running abrt-gui.
If you see lines with ???? characters like this one in the generated trace:

...
#0  0x0000003000eb7472 in ????? () from /usr/lib/libxkbcommon.so.0
...

You simply need to also recompile with debugging symbols the package providing that library (equery b /usr/lib/libxkbcommon.so.0 will point you to the package that owns the offending library) and generate a new backtrace now with that symbols being present. After that, you will get a better backtrace that maybe is finally complete enough (with no ???? or only a few) or you will need to repeat the process with more libraries that will need debugging symbols too.

Finding Xorg logs

Since GDM 3.12, Xorg logs are being redirected to journalctl (from systemd), to review them you will need to run:

root #journalctl --pager-end /usr/bin/Xorg

Major problems

GNOME Shell crashed/hung...

Sometimes something fails and you can see GNOME hangs or crashes, for restarting gnome-shell you can press Alt + F2, type r and press Enter. If it doesn't work, you can try to switch to a console and run killall -9 gnome-shell. If still no luck, you can restart X completely running (in the case of gdm):

root #systemctl restart gdm

Unicode (i.e UTF-8) locale is needed

As reported in bug #481168 (upstream bug#698952), you need to use a UTF-8 locale or, otherwise, you will hit a lot of crashes.

Desktop unresponsive some seconds under heavy I/O load

Sometimes, under heavy I/O load (like while emerging or copying files), you could experience some stalls for a few seconds. You should consider using different IO Schedulers in your kernel and stick with the one performing better for you. Currently three are offered: cfq, deadline and bfq.

Also setting "fs.inotify.max_user_watches=100000" in sysctl.conf can help as reported in upstream bug#712311 and Fedora bug#1069299. Please read /etc/sysctl.d/README for learning about how to handle sysctl.conf settings.

Graphical issues

GDM/GNOME not starting due to 3D issues

If you are having 3D problems related with corrupted images, you could have hit a Xorg driver bug. You need to report a bug for that downstream on Gentoo.

Then, you can additionally add your card to the blacklist to force the usage of software rendering. The file you need to change is /usr/share/gnome-session/hardware-compatibility, and the line you need to append (preceded by a "-") can be obtained running:

user $glxinfo | grep renderer

If you keep having problems, you should check software rendering is ok. To this end, you could need to temporally use x11-misc/lightdm-gtk-greeter as it doesn't need 3D support or re-emerge gnome-base/gdm with USE="-gnome-shell fallback", and run, from a desktop or window manager not relying on 3D:

user $LIBGL_ALWAYS_SOFTWARE=1 LIBGL_DEBUG=verbose glxinfo | grep render

that will likely show you errors loading swrast that could guide us to solve the problem.

Important
You need media-libs/mesa[llvm] for software rendering.

Slow GNOME Shell on NVIDIA card

Sometimes people change nvidia settings using nvidia-settings, this can lead to performace or other problems. Before reporting a issue, you should try to remove your changed settings to use defaults again. Settings are placed at ~/.nvidia-settings-rc.

Video tearing on secondary monitor

Because of a bug with unredirection code in mutter (upstream bug #741376) people can suffer from important tearing on secondary monitor. As a temporal workaround you can disable unredirection each time gnome-shell is started (please note disable tearing forever and unconditionally if neither desired because it would lead to other performance problems with gaming and virtualization for instance):

Run "CLUTTER_PAINT=disable-clipped-redraws:disable-culling gnome-shell --replace"
Press Alt-F2
Type "lg" and press Enter
Type "Meta.disable_unredirect_for_screen(global.screen)" and press Enter

Configuration issues and unexpected behaviors

Cannot terminate X even if I have configured xorg.conf to allow that

GNOME honors XKB options set on xorg.conf.d files (not from old style /etc/X11/xorg.conf file) if the user doesn't have any configuration yet, i.e. for new user accounts. Otherwise previous users configuration is respected.

Unable to change mouse settings from control center

GNOME 3.20 and newer need libinput xorg driver to be used, otherwise you won't be able to configure your mouse settings at all. For that, you need to ensure INPUT_DEVICES is set to libinput and remove any other drivers that could collide with it (like evdev, synaptics, wacom...).

Please note libinput is a complete replacement for synaptics and evdev drivers but, sadly, not all the desktops (i.e MATE) are compatible with libinput yet, hence, if you are a primary user of those desktops, you could prefer to add all the needed drivers to INPUT_DEVICES variable and manually configure the input driver you want to get loaded

Set window theme to default value

In some cases the old metacity window manager theme is migrated and inherited in GNOME Shell. To reset its value to default value you will need to run:

user $gsettings reset org.gnome.desktop.wm.preferences theme

GDM >= 3.16 opens one graphical session per user

As reported at bug #551726, you will see multiple graphical sessions being started by GDM: the first one in tty7 to show login screen and, then, new sessions per user on different free TTYs. This is done on purpose by upstream as explained here to allow to only run the session to choose users as root and all the new ones as the user who is logging in.

If you want to change this behavior to a more classical one, i. e. opening the graphical sessions from tty7 and keeping consoles on lower ones, please follow this tip

Missing emojis and characters

Sometimes the latest Unicode emojis and other characters are not displayed as expected in certain applications. This is likely caused by not having a font set which provides the missing Unicode characters installed. This issue is easily resolved by installing font sets like media-fonts/noto-emoji (color emojis), media-fonts/symbola, or media-fonts/unifont, and then reloading the application:

root #emerge --ask media-fonts/noto-emoji

Project:GNOME/GNOME3 troubleshooting

Contents