Translation(s): English - Italiano - Português (Brasil)

The best way you can learn about your Debian system is to fix your own problems whenever possible. A lot of people have trouble figuring out where to get started looking for answers. Here are some of the first things you should look for.

Reading error messages

Most programs produce meaningful error messages when something goes wrong. You should read these errors and make an honest attempt to understand what they mean. Always start reading from the beginning of the output, because the first error message is often the cause of subsequent errors. (Errors at the end of the output may not be meaningful or relevant once the first error has been corrected.)

There are certain key phrases you should look for in any Unix error message; these are the English (or other native language) translations of the various errno(3) values that are returned by system calls. For example:

someprogram: foobar: No such file or directory

This means that someprogram tried to open a file named foobar, but it couldn't because that file does not exist. Or perhaps it's trying to create foobar but it can't because the directory that it needed to write to doesn't exist yet. Creating the directory for it may fix the problem.

blah blah blah: No such device

This particular error means that a program tried to talk to a device (a file in the /dev directory). The file in the /dev directory exists, but the kernel has no driver to implement this device. This is a kernel-level problem, unless the program simply tried to open the wrong device. In most cases, you'll need to load the driver, or get a different kernel, etc.

some file: Permission denied

This one means that your program tried to open a file but it couldn't because of the file or directory permissions (the ones you can see with ls -l). Take a look at the permissions and verify that they are correct. Run the id(1) command to verify that you're in the right group or are logged in as the right user.

blah blah blah: Operation not permitted

This looks superficially similar to the previous error, but it's actually quite different. Whereas the previous one means the file system permissions stopped you, this one means you tried to make some system call that you aren't allowed to make. For example, you tried to set the system clock when you weren't root. This is the more generic "you aren't allowed to do that" message, and has many many different possible causes.

What Does The Log Say?

Some programs don't produce errors directly on the screen, especially daemons or other background processes. In this case, there will almost always be some sort of log file written to the file system, which will contain useful (or not-so-useful) errors. The location of the logfile varies depending on which program it is, and many other factors.

If it's a system daemon that runs at boot time, then it probably logs using syslog(3). The location of the actual logfiles will therefore be specified in syslog.conf(5). Most of them are in the /var/log directory, though, and if you don't happen to know which one it is, you can frequently use this trick to see the files in chronological order by modification time (mtime):

$ ls -lart /var/log

The most recently modified files will be at the bottom of the screen.

XFree86 version 4.x has its own log file, /var/log/XFree86.0.log, which you should consult if you have any problems with the X server (including the infamous "No screens found" when trying to start X).

Xorg keeps logs in /var/log/Xorg.0.log, which you should consult if you have any problems with the X server.

If you're doing something with your window manager or other X client programs, then their output probably won't be visible to you immediately. The location of their output will depend on how you started X. If you used startx(1) from a console, the output probably appeared on that console (try Ctrl-Alt-F1 to get back to it, then Alt-F7 (usually) to get back to X). If you logged in with xdm(8), then xdm creates a file called .xsession-errors in your home directory, and you should look there. gdm(8) uses .gnome-errors. The other "*dm" programs may have similar files.

Finally, the Linux kernel reports information through a special channel (the ring buffer) which the dmesg(1) command reads. If you're doing anything involving drivers or devices, you should check dmesg to see if there are any errors that may be related to what you're doing. It may also log some messages through syslog which then sends them to systemd journald or another syslog handling daemon.

If you're in sarge or later, you can also enable logging of the userspace messages that occur during system start-up. See bootlogd.

Am I Missing Something?

A lot of the time, errors may be caused by the lack of packages that you were supposed to install, but haven't installed yet. This is quite often the case when you're compiling something, and you don't have the necessary *-dev package(s) installed. See the DevelopmentPage for details on these.

In many other cases, a package may have a "suggests" or "recommends" line for some other package. If you installed your package with dselect(1), these probably got included for you, but if you used apt-get(8), then they were simply printed on the screen. You may have overlooked them. For example, the gs package (Ghostscript) recommends the gsfonts package, but doesn't strictly depend on it. If your package looks like it's only half installed, then look in "apt-cache search" or aptitude(8) or dselect(1) for additional packages that have what you need.

Am I Alone?

Chances are that if you're having a problem, someone else has had it before you (unless you're running unstable...). In fact, the problem may have a known workaround or even a fix. That's why the Debian Bug Tracking System (BTS) is so important. You can use the apt-listbugs package or the reportbug(1) command to search for known problems and their solutions, once you've narrowed your problem down to a specific Debian package. And if you don't find your answer there, you can report your bug so that it can get fixed.

You can also use the following shortcuts to jump straight into the BTS with a browser:

Fill in packagename with the name of a package; or fill in bugnumber with a bug number (they're 6 digits right now). Also note that when the channel topic in #debian says something like "FIXED: foobar (#999999)", that means the bug involved was #999999 in the BTS, and you should go to to see it.

When in Doubt, Search for it!

Even if the first error message looks like gibberish to you, it probably has meaning to someone, especially the programmer who wrote it. Try pasting your exact error message into DuckDuckGo or into your preferred search engine.

ToDo: update references to XFree86 to Wayland and Xorg