Troubleshooting

The purpose of this page is to provide users, in particular new ones, with a set of techniques and tools to allow them to troubleshoot and fix problems with their Gentoo setups on their own. In addition, for those problems which are more complicated, this article seeks to provide users with the skills to collect information that will aid them and their supporters in resolving their issues with a greater degree of expediency.

This article assumes that you have read the Gentoo Handbook and understand the basics of using Gentoo.

Where to Get Help

 * Wikis
 * Gentoo has quite a few wikis all of which have a wealth of information. Be wary that some articles may contain old or outdated information, but hands down, reading wiki articles is always a critical step when using Gentoo.
 * The Official Gentoo Wiki
 * The unofficial Gentoo wiki
 * An Archive of old Gentoo-Wiki.com Articles


 * Knowledge Base
 * For common practices and problems; solutions and more information can be found in our Knowledge Base.


 * IRC
 * For general issues, #gentoo is the recommended channel. This is probably the fastest way to get an answer.


 * Forums and Mailing Lists
 * Since IRC channels require your presence, you might prefer leaving a message at one of these which continues to exist after you close your browser. You will get an e-mail when there is an answer.


 * Bug Tracker
 * When all else fails, and it appears something is broken with Gentoo, this place is a great resource if something has already been reported, or new bugs can be created if need be. This is a very effective way to reach the Gentoo Developers, which can then use your feedback to improve the problematic situation and solve your problem.

Programs
This is a collection of tools that are highly recommended:

Package Management

 * provides a collection of tools for interacting with Gentoo; it includes the valuable `equery`, `eclean`, `euse` and `eshowkw`, see their man pages for more information.
 * provides a collection of tools for interacting with Gentoo; it includes the valuable `equery`, `eclean`, `euse` and `eshowkw`, see their man pages for more information.


 * provides eix, a tool for querying portage for packages
 * provides eix, a tool for querying portage for packages


 * provides e-file, a tool for querying what package contains a given file; it also works for packages that aren't installed since it uses an online lookup.
 * provides e-file, a tool for querying what package contains a given file; it also works for packages that aren't installed since it uses an online lookup.


 * provides genlop, a tool for parsing emerge logs; handy to figure out when certain packages were installed, updated and to see how long they took to compile.
 * provides genlop, a tool for parsing emerge logs; handy to figure out when certain packages were installed, updated and to see how long they took to compile.


 * provides elogv, a ncurses based interface for browsing emerge logs.
 * provides elogv, a ncurses based interface for browsing emerge logs.

Hardware

 * provides lspci, a tool for gathering information about PCI devices.
 * provides lspci, a tool for gathering information about PCI devices.


 * provides lsusb, a tool for gathering information about USB devices.
 * provides lsusb, a tool for gathering information about USB devices.

Monitoring

 * provides htop, a tool for monitoring processes. Like top, but more advanced.
 * provides htop, a tool for monitoring processes. Like top, but more advanced.


 * provides iotop, a top-like tool for monitoring IO activity by process.
 * provides iotop, a top-like tool for monitoring IO activity by process.


 * provides net-top, a top-like tool for examining network traffic by protocol, port, and process.
 * provides net-top, a top-like tool for examining network traffic by protocol, port, and process.

Miscellaneous

 * provides wgetpaste, a tool for uploading text directly to a pastebin.
 * provides wgetpaste, a tool for uploading text directly to a pastebin.


 * provides weechat, a simple text based IRC client.
 * provides weechat, a simple text based IRC client.

First Steps
In order to shape a problem into a solution; you first need to know your problem well enough, if the problem is not clear then you won't be able to come up a solution. An accurate, detailed description of the problem is more likely to yield a solution that best fits the problem.

Identifying the Problem
This part may seem like it's a no-brainer, but without it, any troubleshooting will be next to impossible.

Take note of a few things:
 * 1) Is this problem related to hardware or software?
 * 2) Can you remember if you did something recently that may have been the cause of this issue?
 * 3) Can you collect additional information about it?

Storing any form of detail, logs, other people experiencing it and more can be valuable and gives you a good overview.

Drivers
Drivers issues for hardware is one of the more common issues that we see in IRC. First and foremost, we should identify what the hardware is that we are having issue with. lspci and lsusb are great tools for this purpose. For demonstration purposes, we'll be looking at my ethernet card as the troublesome device.

Determining the Proper Driver
With lspci we can see our card very clearly:

It is also possible to use the -n option:

Assuming that we weren't sure what driver we needed, the model name in the first, and vendor:model code of the second are all that we need to look up the device on a place like WikiDevi or Debian HCL

Verifying the Driver is Loaded
Getting the driver is less than half of the battle. Most of the trouble with drivers is making sure that they are loaded and operating correctly. Relying on our friend lspci again, we run:

Note that here, we have text indicating that a driver is in use. If not, we weren't able to successfully load the driver. Assuming the driver was built as a module rather than builtin, try modprobe  to attempt loading the module. If your driver was builtin, consider making it a module while you debug why it isn't working, because you can load a module with modprobe and unload a module with modprobe -r.

Troubleshooting a Driver
Compile your driver as a module, then you can capture the output it generates when you modprobe it again; make sure to first remove all modules that depend on your driver (see `lsmod`).

The following command will compare the dmesg output after your removed the module (in this example, r8169) with the output after you add the module again, effectively showing the messages that were added (lines starting with +).

The most common issue is missing firmware, if you see that it is telling that firmware is missing you should grab either sys-kernel/linux-firmware or a specific firmware package from Portage.

Dependency Graph Slot Conflicts
Occasionally, you will see messages like this when trying to emerge a package: !!! Multiple package instances within a single package slot have been pulled !!! into the dependency graph, resulting in a slot conflict:

Generally, this means that the packages listed have multiple requested versions in the dependency graph. And fortunately most, if not all cases that you will encounter, you can resolve by manually upgrading to the highest requested version. So assuming that you get the following exact message: app-emulation/emul-linux-x86-xlibs:0 (app-emulation/emul-linux-x86-xlibs-20120127::gentoo, installed) pulled in by ~app-emulation/emul-linux-x86-xlibs-20120127 required by (app-emulation/emul-linux-x86-medialibs-20120127::gentoo, installed) (and 2 more with the same problem) (app-emulation/emul-linux-x86-xlibs-20120520::gentoo, ebuild scheduled for merge) pulled in by >=app-emulation/emul-linux-x86-xlibs-20120520 required by (net-im/skype-2.2.0.35-r99::gentoo, ebuild scheduled for merge) ~app-emulation/emul-linux-x86-xlibs-20120520 required by (app-emulation/emul-linux-x86-medialibs-20120520::gentoo, ebuild scheduled for merge)

we see that most recent version desired is 20120520, so we just

and we are good to go. Often, it's advantageous to oneshot all of the conflicts at once because they sometimes depend on one another.

Here is another example of a block.

app-text/poppler:0 (app-text/poppler-0.24.5::gentoo, installed) pulled in by   app-text/poppler:0/44=[xpdf-headers(+)] required by (dev-tex/luatex-0.76.0::gentoo, installed) app-text/poppler:0/44=[cxx,jpeg,lcms,tiff,xpdf-headers(+)] required by (net-print/cups-filters-1.0.43::gentoo, installed) (app-text/poppler-0.24.3::gentoo, ebuild scheduled for merge) pulled in by   >=app-text/poppler-0.12.3-r3:0/43= required by (app-text/texlive-core-2013-r1::gentoo, installed) poppler:0/43

We should have no problem changing poppler versions. Note that luatex and cups-filters don't require a specific version of poppler, but they need to be rebuild with whatever version is used:

Collecting Additional Information
When seeking help, it's best to come prepared. Someone volunteering their time doesn't want to waste that time fumbling about. That's where wgetpaste comes in handy. make sure you have merged wget paste, and then you're ready to be helped.

Let's say you want to show your configuration file /etc/conf.d/net, using wgetpaste is as simple as:

Or let's say that you want to show what the detailed output of your lspci command is, you can just run:

Sometimes you need to redirect stderr to stdout so that you can paste error messages. That can be done like this:

These return a link to a pastebin that you can easily share with someone to get help. Things that you should consider pasting if you want help:

If you have hardware problems or kernel issues:

If you have portage issues:

If compilation of a package fails:

If you are having issues with Xorg:

Forming a solution
With a good description of the problem, your history of actions and all sorts of debugging data (problem details, hardware / software information, logs, backtraces and more) you have a good set of useful data to look for a solution.

In general, you will want to repeat the following steps:


 * Get an idea where the problem might be, think about possible causes.
 * If you don't know the area the cause may lie in well enough, become more acquainted with that area or ask an expert in that area more about it.
 * Sometimes you need to make assumptions to proceed, it is important that when you do make an assumption you should put it to the test; false assumptions should not make you blind of other causes.
 * When you feel like you are heading in the right direction, but are not quite there; you may want to obtain additional debugging information in the area of your problem, or perform tests.

Often you will find that this leads to multiple possible causes, it in important that you try to test them (to verify it is the actual cause or not) and therefore test them individually; this is also known as "divide and conquer".

Let's say we had a problem like "my browser sometimes displays white pages when I boot" and we know a lot of details about it, then there may be a various amount of possible causes:


 * Is this because I improperly closed the browser and rebooted?
 * You can verify this by killing the process and pulling the plug several times, each time checking if the pages are white after booting again. If we found this to be a cause, is it the actual cause or are there other causes?


 * Is this the result of a specific browser version being broken?
 * You can try older or newer versions for a few days or reboots and see if they are broken as well.

And so on...

With the additional information, we can even think about more specific causes:


 * Does a certain pinned tab X that loads plugin Y break my system?
 * Unpin the tab so it doesn't open on launch anymore or disable the plugin, see if this keeps the problem away.


 * Graphical issues were reported as well, might this maybe mean this is caused by the video drivers?
 * Try different version for those drivers, or alternative drivers if available.

As we try dealing with each possible cause, we may find the actual cause of the problem.

And if you are still stuck, the "Where to Get Help" resources at the top of this article yield a multitude of places with people that are looking forward to help you; make them happy with a careful problem description and mentioning what you have tried so far, it'll help them help you.