This article explains some methods for general troubleshooting. For application specific issues, please reference the particular wiki page for that program.
It is crucial to always read any error messages that appear. Sometimes it may be hard, e.g with graphical applications, to get a proper error message.
- Run the application in a terminal so it is possible to inspect the output.
- Increase the verbosity (usually
-d) if there is still not enough information to debug.
- Sometimes there is no such parameter and it needs to be specified as a directive in the applications' configuration file.
- An application may also use log files, which are usually located in
- If there is no way to increase the verbosity, it is always possible to run strace and similar.
- Increase the verbosity (usually
- Check the journal. It is possible that an error may also leave traces in the journal, especially if it depends on other applications.
dmesgreads from the kernel ring buffer. This is useful if the disk is for some reason inaccessible but this may also result in incomplete logs because the kernel ring buffer is not infinite in size. Use
journalctlhas more filtering options than
dmesgand uses human-readable timestamps by default.
- It is always recommended to check the relevant issue trackers to see if there are known issues with already existing solutions.
- Depending on upstreams' choices, there is usually an issue tracker and sometimes also a forum or even e.g an IRC channel.
- There is the Arch Linux bugtracker, which should be primarily used for packaging bugs.
When asking for support post the complete output/logs, not just what you think are the significant sections. Sources of information include:
- Full output of any command involved - do not just select what you think is relevant.
- systemd's journal.
- For more extensive output, use the
systemd.log_level=debugboot parameter. This will produce a tremendous amount of output, so only enable it if it really needed.
- Do not use the
-xparameter because this needlessly clutters the output and makes it harder to read.
-bunless you need logs from a previous boot. Not specifying this may lead to extremely large pastes that may even be too big for any pastebins.
- For more extensive output, use the
- Relevant configuration files
- Drivers involved
- Versions of packages involved
dmesg(both with root privileges).
- Xorg: depending on the setup the display manager in use is relevant here, too.
Xorg.logmay be located in one of several places: the system journal,
- Some display managers like LightDM may also place the
Xorg.login its own log directory.
- Pacman: If a recent upgrade broke something, look in
- It may be useful to use pacman's
- It may be useful to use pacman's
One of the better ways to post this information is to use a pastebin.
A link will then be output that you can paste to the forum or IRC.
Additionally, you may wish to review how to properly report issues before asking.
When diagnosing boot problems, it is very important to know in which stage the boot fails.
- Firmware (UEFI or BIOS)
- Usually only has very basic tools for debugging.
- Make sure Secure Boot is disabled.
- Boot loader
- One of the most common things done here is the changing of kernel parameters.
- Usually provides an emergency shell.
- Depending on the hooks chosen, either the dmesg or the journal is available within it.
- The actual system
- Depending on how badly it is broken, a simple invocation of the debug shell may suffice here.
Unfortunately, the debugging tools provided by any stage may not be enough to fix the broken component. The archiso may be used to recover in this case.
After the boot process, the screen is cleared and the login prompt appears, leaving users unable to read init output and error messages. This default behavior may be modified using methods outlined in the sections below.
Note that regardless of the chosen option, kernel messages can be displayed for inspection after booting by using
journalctl -k or
dmesg. To display all logs from the current boot use
This is basic management that applies to most terminal emulators, including virtual consoles (VC):
Ctrl+sto pause the output.
Ctrl+qto resume it.
This pauses not only the output, but also programs which try to print to the terminal, as they will block on the
write() calls for as long as the output is paused. If your init appears frozen, make sure the system console is not paused.
To see error messages which are already displayed, see Getty#Have boot messages stay on tty1.
Most kernel messages are hidden during boot. You can see more of these messages by adding different kernel parameters. The simplest ones are:
debugenables debug messages for both the kernel and systemd
ignore_loglevelforces all kernel messages to be printed
Other parameters you can add that might be useful in certain situations are:
earlyprintk=vga,keepprints kernel messages very early in the boot process, in case the kernel would crash before output is shown. You must change
efifor EFI systems.
log_buf_len=16Mallocates a larger (16 MiB) kernel message buffer, to ensure that debug output is not overwritten.
There are also a number of separate debug parameters for enabling debugging in specific subsystems e.g.
initcall_debug can be useful to investigate boot freezes. (Look for calls that did not return.) Check the kernel parameter documentation for specific information.
netconsole is a kernel module that sends all kernel log messages (i.e. dmesg) over the network to another computer, without involving user space (e.g. syslogd). Name "netconsole" is a misnomer because it is not really a "console", more like a remote logging service.
It can be used either built-in or as a module. Built-in netconsole initializes immediately after NIC cards and will bring up the specified interface as soon as possible. The module is mainly used for capturing kernel panic output from a headless machine, or in other situations where the user space is no more functional.
Getting an interactive shell at some stage in the boot process can help you pinpoint exactly where and why something is failing. There are several kernel parameters for doing so, but they all launch a normal shell which you can
exit to let the kernel resume what it was doing:
rescuelaunches a shell shortly after the root filesystem is remounted read/write
emergencylaunches a shell even earlier, before most filesystems are mounted
init=/bin/sh(as a last resort) changes the init program to a root shell.
emergencyboth rely on systemd, but this should work even if systemd is broken.
Another option is systemd's debug-shell which adds a root shell on
tty9 (accessible with
Ctrl+Alt+F9). It can be enabled by either adding
systemd.debug_shell to the kernel parameters, or by enabling
Debugging kernel modules
- You can display extra debugging information about your hardware by following udev#Debug output.
- Ensure that Microcode updates are applied on your system.
- To test the RAM, see Stress testing#Stressing memory.
- To see if your system is overheating, use Lm sensors.
- To check your storage health, see S.M.A.R.T.
Unfortunately, freezes are usually hard to debug and some of them take a lot of time to reproduce. There are some types of freezes which are easier to debug than others:
- Is sound still playing? If so, just the display may be frozen. This may be a problem with the video driver.
- Is the machine still responding? Try SSH if switching to another TTY does not work.
- Is the disk activity LED (if present) indicating that a lot is being written to disk? Heavy swapping may temporarily freeze the system. See this StackExchange answer for information about freezes on large writes.
If nothing else helps, try a clean shutdown. Pressing the power button once may unfreeze the system and show the classic "shutdown screen" which displays all the units that are getting stopped. Alternatively, using the magic SysRq keys may also help to achieve a clean shutdown. This is very important because the journal may contain hints why the machine froze. The journal may not be written to disk on an unclean shutdown. Hard freezes in which the whole machine is unresponsible are harder to debug since logs can not be written to disk in time.
Remote logging may help if the freeze does not permit writing anything to disk. A crude remote logging solution, which needs to be invoked from another device, can be used for basic debugging:
$ ssh freezing_host journalctl -f
Many fatal freezes in which the whole system does not respond anymore and require a forced shutdown may be related to buggy firmware, drivers or hardware. Trying a different kernel (see Kernel#Debugging regressions) or even a different Linux distribution or operating system, updating the firmware and running hardware diagnostics may help finding the problem.
If a freeze does not permit gathering any kind of logs or other information required for debugging, try reproducing the freeze in a live environment. If a graphical environment is required to reproduce the freeze or if the freeze can be reproduced on the archiso, use the live environment of a different distribution, which is preferably not based on Arch Linux to eliminate the possibility that the freeze is related to the version or patches of the kernel. Should the freeze still happen in a live environment, chances are that it may be hardware-related. If it does not happen anymore, it is necessary to be aware of the differences of both systems. Different configurations, differences in versions and kernel parameters and other, similar changes may have fixed the freeze.
However, a blinking caps lock LED may indicate a kernel panic. Some setups may not show the TTY when a kernel panic occurred, which may be confusing and can be interpreted as another kind of freeze.
If an update causes an issue but downgrading the specific package fixes it, it is likely a regression. The most important part of debugging regressions is checking if the issue was already fixed, as this can save much time. To do so, first ensure the application is fully updated (e.g ensure the application is the same version as in the official repositories). If it already is or if updating it does not fix the issue, try using the the actual latest version, usually a -git version, which may already be packaged in the AUR. If this fixes the issue and the version with the fixes is not yet in the official repositories, wait until the new version arrives in them and then switch back to it.
If the issue still persists, debug the issue and/or bisect the application and report the bug on the upstream bugtracker so it can be fixed.
Cannot use new peripherals after kernel upgrade
This will manifest commonly (but probably not only) as :
- newly plugged USB storage devices showing up with dmesg but not in
- the inability to use a wired/wireless connection on a laptop if it was not already used before the kernel update,
FATAL: Module module not found in directory /lib/module/kernelversionwhen using modprobe to load a module that was not already used before the kernel package update.
As partially covered in System maintenance#Restart or reboot after upgrades, the kernel is not updated when you update the package but only once you reboot afterwards. Meanwhile, the kernel modules, located in
/usr/lib/module/kernelversion/ are removed by pacman when installing the new kernel. As explained in FS#16702, this approach avoids leaving files on the system not handled by the package manager but leads to the aforementioned symptoms. To fix them, reboot systematically after updating the kernel. The long-term evolution, yet to be implemented, will be to use versioned kernel packages : the main blocker being how to handle the removal of the previous kernel versions once they are not needed anymore.
Another solution is available as, where two pacman hooks use rsync to keep the kernel modules on the filesystem after the kernel update and a systemd service removes the old modules four weeks after.
Fixing a broken system
If a partial upgrade was performed, try updating your whole system. A reboot may be required.
# pacman -Syu
If you usually boot into a GUI and that is failing, perhaps you can press
Ctrl+Alt+F6 and get to a working tty to run pacman through.
If the system is broken enough that you are unable to run pacman, boot using a monthly Arch ISO from a USB flash drive, an optical disc or a network with PXE. (Do not follow any of the rest of the installation guide.)
Mount your root filesystem:
[ISO] # mount /dev/rootFilesystemDevice /mnt
Mount any other partitions that you created separately, adding the prefix
/mnt to all of them, i.e.:
[ISO] # mount /dev/bootDevice /mnt/boot
Try using your system's pacman:
[ISO] # arch-chroot /mnt [chroot] # pacman -Syu
If that fails, exit the chroot, and try:
[ISO] # pacman -Syu --sysroot /mnt
If that fails, try:
[ISO] # pacman -Syu --root /mnt --cachedir /mnt/var/cache/pacman/pkg
IRC collaborative debugging
fuser is a command-line utility for identifying processes using resources such as files, filesystems and TCP/UDP ports.
fuser is provided by the meta package. See for details.package, which should be already installed as a dependency of the
First, make sure you have a valid local session within X:
$ loginctl show-session $XDG_SESSION_ID
This should contain
Active=yes in the output. If it does not, make sure that X runs on the same tty where the login occurred. This is required in order to preserve the logind session.
Basic polkit actions do not require further set-up. Some polkit actions require further authentication, even with a local session. A polkit authentication agent needs to be running for this to work. See polkit#Authentication agents for more information on this.
If, while using a program, you get an error similar to:
error while loading shared libraries: libusb-0.1.so.4: cannot open shared object file: No such file or directory
$ pacman -F libusb-0.1.so.4
extra/libusb-compat 0.1.5-1 usr/lib/libusb-0.1.so.4
The error could also mean that the package that you used to install your program does not list the library as a dependency in its PKGBUILD: if it is an official package, report a bug; if it is an AUR package, report it to the maintainer using its page in the AUR website.