Guidelines and HOWTOs/Debugging/How to create useful crash reports
Note
A good crash report at Bugzilla consists of two parts: a description of how to reproduce the crash and a backtrace of the crash. With one of those elements missing, it is much harder (if not impossible) for developers to tackle the problem.
A description should consist of more than only "it crashed": try to describe everything you did prior to the crash. Did you click on a button or open a particular website or file? That little detail which may look useless to you may be useful for the developer, so just write it down.
Backtraces
Backtraces are essential. They may look meaningless to you, but they might actually contain a wealth of useful information. A backtrace describes which functions were called prior to the crash, so that developers may track down in which function the mess started. Having good backtraces has a downside: libraries and executables occupy much more disk space than their optimized counter parts. That's the reason why many distros choose to install stripped files which result in useless backtraces. But don't worry; with some modifications you can create full blown useful backtraces for KDE applications.
Note
Install debugging packages
If your distribution has debugging-enabled packages, install them.
It is easy to see which debug packages you are missing from looking at the backtrace. For example, take the following line from a backtrace:
#6 0xb7975bdc in ?? () from /usr/lib/libkmailprivate.so.4
The ?? indicates that the library libkmailprivate.so.4 does not have debug information, which might be available in separate debug packages. In this case, it is pretty easy to guess that you need to install debug packages for KMail to get a better backtrace.
Sometimes, you need to install more than one debug package to get a good backtrace. This depends on how the distribution splits up the packages. For example, for some distributions it is enough to install the debug package for kdepim to get enough debugging information for a crash in KMail, for other distributions there is an additional debug package just for KMail.
Here's a list of how to obtain debug packages for some distributions:
Arch Linux
Arch Linux provides debug packages via its debuginfod server. To use them, install the debuginfod package or set the environment variable DEBUGINFOD_URLS="https://debuginfod.archlinux.org". See their informative document Getting Traces.
Debian
Debian offers -dbg packages to easy create useful backtraces. Just install the corresponding -dbg package. e.g. kdepim-dbg for KMail crashes. The dependencies of -dbg makes sure to pull in the other needed packages. See also the Debian document on How to get a Backtrace.
Fedora
Recent versions of Fedora (e.g. Fedora 37) have debuginfod. See https://fedoraproject.org/wiki/Debuginfod .
If your version of Fedora does not have debuginfod, see below.
In Fedora you need to open a terminal and enter :
- dnf provides "*/libkmailprivate.so.4"
to find out which package provides that file. The reason to replace the path /usr/lib with * is that some installation paths are symbolic links to other directories; dnf provides should resolve the wildcard. - sudo dnf debuginfo-install kmail-libs
to install (as root) the debug packages for that package, and its dependencies.
StackTraces is a complete and detailed guide for Fedora describing how to proceed. Fedora uses a separate debuginfo repository that has to be enabled, `dnf debuginfo-install` should do this.
FreeBSD ports
You need to recompile the concerned packages with the flag WITH_DEBUG. Please refer to the KDE on FreeBSD FAQ.
Gentoo
Gentoo has its own web page describing how to proceed.
Ubuntu-based distros (Ubuntu, Kubuntu, KDE Neon, Linux Mint)
(K)Ubuntu has debuginfod starting with 22.10. See https://ubuntu.com/server/docs/service-debuginfod https://ubuntu.com/blog/debuginfod-is-now-available-in-ubuntu .
For Linux distributions based on versions of Ubuntu previous to 22.10, see below.
(K)Ubuntu in particular has debug symbols packages in a separate repositories as describe at https://wiki.ubuntu.com/Debug%20Symbol%20Packages.
Neon has the debug symbols in its regular repository.
The Ubuntu family makes things quite easy. Every official KDE module has an additional package in the repository, suffixed with -dbgsym. You should install a -dbgsym package for the application which crashed. For example if Okular crashed you should install okular-dbg. If the program is not from an official KDE module and has no -dbg package, you can install the -dbgsym package from the repository listed on this Debugging Program Crashes page.
- During the Ubuntu development cycle the Apport crash handler is turned on which will report crashes to launchpad.net and do the backtrace for you, if you would rather use the KDE crash handler turn Apport off in /etc/defaults/apport
- Starting with Lucid Lynx (10.04) Kubuntu will be forwarding all non kubuntu specific bugs upstream and had disabled Apport so that DrKonqi will be the default crash handler.
Mageia
Mageia offers -debug packages in a separate repository. See their wiki page.
openSUSE
openSUSE Tumbleweed x86_64 has experimental support for debuginfod. See https://debuginfod.opensuse.org/
If not using debuginfod, you should only install the -debuginfo packages, for example: kdepimlibs4-debuginfo. You can find these packages in KDE repositories. There is also a dedicated openSUSE debugging page.
Solus
Solus separates debugging symbols by default but they are included in the official repository and are easy to install. For instance if you need symbols for knotifyconfig you simply install knotifyconfig-dbginfo via the Software Center or via eopkg.
Finding the package that provides the symbol is done like so:
#6 0xb7975bdc in ?? () from /usr/lib64/libkwin.so.5
Use the filename in this case libkwin.so.5 in eopkg search-file:
eopkg search-file libkwin.so.5
This gives kwin as the package name, you can then search for kwin and find the debug symbols package:
eopkg search kwin | grep dbginfo kwin-dbginfo - Debug symbols for kwin
Compile from sources
If your distribution doesn't have debugging-enabled packages for KDE, you'll have to compile the software from source code. See Get_Involved/development
Retrieving a backtrace using the KDE Crash Report tool
Do whatever you did to make the application crash, and crash it again! The KDE Crash Report dialog should appear right after the crash, which shows the "Developer Information" tab.
Click that tab and wait for a minute. This process may take quite some memory, so things may go sluggish all of a sudden. But the result should look much better.
Note
Retrieving a backtrace with GDB
In some cases, it is not possible to create a backtrace with the KDE Crash Dialog. This may be caused by an application which entered an infinite loop, or the crash dialog did not appear at all for some reason. You can try to grab a backtrace with gdb, the GNU Debugger. GDB is widely available through distribution packages.
You can run an application from inside gdb, or attach gdb to an already running process. The latter may be useful when an application already has entered an infinite loop. But we will first start with running an application inside gdb. From the shell, run:
$ gdb someKDEapp
The GDB prompt will appear. Note that this does not start the application itself, so you should immediately run it by invoking the run command:
(gdb) run
This will run the application like you are used to, and you can work with it like normal (it only consumes far more memory and may feel sluggish). Now it's time to reproduce your crash. When you succeed, the application just closes and you should return to your GDB prompt.
Note
Now it's time to run the 'backtrace' command:
(gdb) backtrace
This should give a good backtrace which can be posted at the KDE Bugzilla.
In case you want to attach to an existing process, run the following command in the shell:
$ gdb someKDEapp pid
where pid is the process ID of the process you want to attach to. Once attached, and the process is in an infinite loop, after using the 'backtrace' command again a useful backtrace will appear. You can use 'continue' command to let the application run again and press Ctrl+C in gdb to be able to again enter commands.
Retrieving a backtrace when an uncaught exception is causing a crash
If your backtrace looks like this:
Thread 1 (Thread 0xb77be730 (LWP 5794)): [KCrash Handler] #7 0x00e9b416 in __kernel_vsyscall () #8 0x002b1c8f in raise () from /lib/i386-linux-gnu/libc.so.6 #9 0x002b52b5 in abort () from /lib/i386-linux-gnu/libc.so.6 #10 0x001c14ed in __gnu_cxx::__verbose_terminate_handler() () from /usr/lib/i386-linux-gnu/libstdc++.so.6 #11 0x001bf283 in ?? () from /usr/lib/i386-linux-gnu/libstdc++.so.6 #12 0x001bf2bf in std::terminate() () from /usr/lib/i386-linux-gnu/libstdc++.so.6 #13 0x001bf464 in __cxa_rethrow () from /usr/lib/i386-linux-gnu/libstdc++.so.6 [...]
then only GDB can help to get a useful backtrace. A few more commands are needed. From the shell, run:
$ gdb someKDEapp
Then start loading the application:
(gdb) start
The GDB prompt will reappear. Turn logging on:
(gdb) set logging file ~/gdblog.txt (gdb) set logging on
We must now tell gdb to stop just before the exception is thrown. enter:
(gdb) break __cxa_throw (gdb) break __cxa_rethrow
and finally:
(gdb) cont
Now reproduce the crash. When you succeed, the application window will look frozen.
Don't worry and switch back to the shell window. If you see the gdb prompt, type:
(gdb) backtrace
press enter until the (gdb) prompt reappears.
All done! you can now quit gdb:
(gdb) kill
The kill command will stop the program and now enter:
(gdb) quit
Copy/paste the content saved in the ~/gdblog.txt file to your bug report.
Retrieving a backtrace using coredumpctl
If your application crashed in the past and you cannot get it to crash again, it is often possible to retrieve the backtrace anyway using the coredumpctl tool.
Run coredumpctl and then scroll to the bottom by holding down the spacebar key. You will see output like this:
Thu 2020-12-17 20:11:19 MST 21396 1000 100 11 present /home/nate/kde/usr/bin/baloo_file Fri 2020-12-18 09:50:54 MST 30913 1000 100 11 present /home/nate/kde/usr/bin/systemsettings5 Fri 2020-12-18 12:17:45 MST 30742 1000 100 11 present /home/nate/kde/usr/bin/dolphin Fri 2020-12-18 13:47:18 MST 30930 1000 100 11 present /home/nate/kde/usr/bin/neochat
Find the table row that corresponds to the crashing app; the name of its executable fie will be listed in the last column. The second column lists a number; copy that number.
Then run the following command:
$ coredumpctl gdb [paste the number]
It may take some time for something to happen. Eventually you will see a "(gdb)" prompt. Type bt at the prompt and hit the Enter/Return key. Then copy the output that appears and paste it into the bug report in question.
Retrieving a backtrace with Valgrind
When it comes to crashes, Valgrind is also a useful tool to create a backtrace. It's not a substitution for GDB, but rather a supplement.
When you run an application in valgrind, every piece of memory read or written by the application is being checked. Valgrind will report erroneous memory operations in the standard output or in a log file. Since most crashes are due to an invalid memory read, valgrind can be useful to track down where the problem occurs.
Note
Like GDB, Valgrind makes running an application much slower, while consuming a lot more resources.
Start the application within valgrind:
$ valgrind --log-file=someKDEapp someKDEapp
Now reproduce the crash. As soon as this happens, the application and valgrind will terminate. What's left is a file named someKDEapp.pid where pid is replaced by the process ID of the valgrind process. The file may list more errors than the one causing the crash. Here's the bit causing the crash which corresponds to the GDB backtrace above:
==23292== Invalid read of size 4 ==23292== at 0x806BD9E: TreeMapItem::parent() const (treemap.h:285) ==23292== by 0x8065FB9: TreeMapItemList::compareItems(void*, void*) (treemap.cpp:720) ==23292== by 0x50AC618: QGList::operator==(QGList const&) const (in /usr/qt/3/lib/libqt-mt.so.3.3.8) ==23292== by 0x806D3BF: QPtrList<TreeMapItem>::operator==(QPtrList<TreeMapItem> const&) const (qptrlist.h:74) ==23292== by 0x8062DE7: TreeMapWidget::mousePressEvent(QMouseEvent*) (treemap.cpp:1840) ==23292== by 0x4E2FA62: QWidget::event(QEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8) ==23292== by 0x4D96CA6: QApplication::internalNotify(QObject*, QEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8) ==23292== by 0x4D97A87: QApplication::notify(QObject*, QEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8) ==23292== by 0x4809AC3: KApplication::notify(QObject*, QEvent*) (kapplication.cpp:550) ==23292== by 0x4D36FD1: QETWidget::translateMouseEvent(_XEvent const*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8) ==23292== by 0x4D368AF: QApplication::x11ProcessEvent(_XEvent*) (in /usr/qt/3/lib/libqt-mt.so.3.3.8) ==23292== by 0x4D46760: QEventLoop::processEvents(unsigned) (in /usr/qt/3/lib/libqt-mt.so.3.3.8) ==23292== Address 0x2C is not stack'd, malloc'd or (recently) free'd
But to be sure, just attach the whole log file to the crash report.
Add application-specific details
For some KDE software, it's helpful to include specific details of how you were using it inside the bug report:
- Plasma Desktop: Plasmoids you have in your desktop (both official and unofficial), desktop settings (wallpaper plugin, themes), activities and dashboard configuration. For more information, see the Plasma debugging page.
- KWin (the window manager): state of compositing (desktop effects): enabled / suspended / disabled, kind of effects enabled, window decoration. For more information, see the KWin debugging page.
- Dolphin: file view mode, grouping and sorting settings, preview settings, directory you were browsing.
- KMail: Mail protocols and account-types you use.
- KWrite/Kate: Type of the document you were editing.
- Juk/Dragon/Amarok (and other multimedia players): Type of media (extension and format) you were watching and/or listening to.
- Discover: If it crashed during a search, include what you were searching for and what page you were on when it crashed.