HGKeeper

---

title: Debugging

date: 2021-07-10T09:04:12.000Z

anchor: debugging

replaces:

- developer.pidgin.im/wiki/GetABacktrace

- developer.pidgin.im/wiki/TipsForBugReports

aliases:

- /development/wiki/GetABacktrace

lastmod: 2021-07-11T19:04:12.000Z

---

Issues in Pidgin are sometimes hard to troubleshoot so it's of key importance to

understand how to obtain the necessary information so that developers can

understand what causes the issue. In this section, we'll explain the two methods

that are usually followed when troubleshooting issues in Pidgin.

If you are reading this because you are facing an issue and want to submit a bug

report, make sure you read the [related page]({{< ref

"development/contributing#submitting-a-bug-report" >}}) before doing so.

## Obtaining a debug log

Debug logs contain messages generated by Pidgin and can help understand what was

the application doing before a specific event (most likely a bug) got triggered.

Debug logs can be obtained through the Pidgin user interface by opening the

Debug Window (Help -> Debug Window). However, if Pidgin is crashing and you

cannot get the debug logs from there, read the following instructions according

to the operating system you are using to get the debug logs outputted into a

file.

### All OS except Windows

Open a terminal and start Pidgin as follows:

```

pidgin --debug |& tee ~/debug.log

```

This will save the debug logs generated by Pidgin in a `debug.log` file that

will be placed in the home directory of the user executing the command.

## Windows

Open a Command Prompt window and start Pidgin as follows:

```

cd "C:\Program Files (x86)\Pidgin"

pidgin.exe --debug 2>&1 > "%USERPROFILE%\debug.log"

```

**Note:** `C:\Program Files (x86)\` is the default path where Pidgin will be installed

to, if you installed Pidgin to a different directory make sure you use it when

running the commands expressed above.

This will save the debug logs generated by Pidgin in a file called `debug.log`

that will be placed in the `%USERPROFILE%` directory, which normally evaluates

to `C:\Users\username`.

## Obtaining a backtrace

If Pidgin or Finch has crashed, one of the first things you'll want to do before

submitting a bug is getting a backtrace. Useful backtraces will help Pidgin

developers find where in Pidgin, Finch, or LibPurple the bug got triggered and

from there think about how to find a fix for it.

### All OS except Windows

#### Prerequisites

The most important prerequisite before being able to get a backtrace is to make

sure that you have the debugging symbols for pidgin, libpurple and finch

installed.

Please follow the instructions below if you are using one of these distributions

for more details on how to achieve this. If you are using a different

distribution then we recommend you to look for a similar page in the

documentation or find out what packages/configuration is needed before you can

get useful backtraces.

- Ubuntu: see the [Ubuntu wiki page](https://wiki.ubuntu.com/Backtrace) on

obtaining backtraces.

- Debian: see the [Debian wiki page](http://wiki.debian.org/HowToGetABacktrace)

on obtaining backtraces.

- Fedora: Install the `-debuginfo` rpm first. See [these

instructions](http://fedoraproject.org/wiki/StackTraces) for more details.

- Red Hat Enterprise Linux: Install the `-debuginfo` rpm first, then follow our

instructions below.

- Gentoo: emerge pidgin with`USE=debug`. See the [gentoo wiki

page](https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces) for

more details.

- Arch Linux: see the [Arch wiki

page](http://wiki.archlinux.org/index.php/Debug_-_Getting_Traces) on obtaining

backgraces, build the debug version of Pidgin and follow the instructions

below.

#### Getting traces

The easiest way to obtain a backtrace for Pidgin is by running with gdb. If you

are trying to get a trace for Finch, then make sure you read [GDB and finch]({{<

ref "#gdb-and-finch" >}}). Here are the basics:

1. Run the application with gdb and specify to save the output to a file:

```

$ gdb --args pidgin --debug |& tee ~/pidgin-backtrace.log

```

1. Next, you'll see some information from gdb similar to this:

```

GNU gdb (Debian 10.1-1.7) 10.1.90.20210103-git

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

This is free software: you are free to change and redistribute it.

There is NO WARRANTY, to the extent permitted by law.

Type "show copying" and "show warranty" for details.

This GDB was configured as "x86_64-linux-gnu".

Type "show configuration" for configuration details.

For bug reporting instructions, please see:

<https://www.gnu.org/software/gdb/bugs/>.

Find the GDB manual and other documentation resources online at:

<http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".

Type "apropos word" to search for commands related to "word".

```

1. Start the application from within the debugger by executing the following

commands:

```

(gdb) handle SIGPIPE nostop noprint

(gdb) run

```

1. Information will pass by now and Pidgin will start. You should reproduce your

crash now, and once the crash has happened do the following:

```

(gdb) bt full

```

When you get the backtrace, instead of seeing function names, you might see '??'

instead. If that's the case, gdb couldn't read the function names from Pidgin

and so the backtrace won't end up being very useful after all. These means that

you are not meeting the [prerequisites]({{< ref "#prerequisites" >}}) stated at

the beginning of this section. If you see function names, then the backtrace is

good and can be attached to your bug report.

1. Look for the `~/pidgin-backtrace.log` file where the contents of the

backtrace should have been saved and attach it to your bug report.

#### GDB and finch

If you are trying to obtain a backtrace for Finch you need to do something

different as Finch is a console-based application. Assuming that finch will at

least start up without crashing, you can attach gdb to a running finch process

from a second terminal in order to debug it. Thus, instead of doing as you would

with Pidgin (`gdb finch` and then `run`), you will do the following:

1. Start finch as you normally would in a terminal.

1. Once finch is up and running, open a second terminal and find its process ID

using, e.g., the `ps` or the `pidof` commands.

1. Once you have its process ID (also known as *pid*), run in the second

terminal:

```

$ gdb finch <pid>

```

1. The finch process will become unresponsive, this is expected. Now similar to

before, run:

```

(gdb) handle SIGPIPE nostop noprint

(gdb) continue

```

Note the use of `continue` instead of `run`. From here on out, to get the

backtrace follow the same instructions for Pidgin after the `run` command was

executed.

### Windows

- Make sure that you have the "Debug Symbols" for your current Pidgin version.

These are installed by selecting a checkbox in the Pidgin installer. You can

verify if you have the debug symbols by checking if you have a

`pidgin-x.y.z-dbgsym` (with x.y.z matching the Pidgin version you have

installed) directory in your Pidgin installation directory.

- The next time you run Pidgin and it crashes, the call stack will be dumped to

a `pidgin.RPT` file in your `%PURPLEHOME%\.purple` directory. Unless you

changed it, the default value of `%PURPLEHOME%` matches `%APPDATA%` so in most

cases you want to look for the `C:\Users\username\AppData\Roaming\.purple`

directory.

- When [submitting a bug report]({{< ref

"development/contributing#how-to-submit-a-bug-report" >}}) remember to attach

the most recent crash dump from the aforementioned `pidgin.RPT` file.

**Note:** Each new crash dump will *append* to the `pidgin.RPT` file, so if

you have several crashes all the dumps will be present. Thus, it may be a good

idea to delete the file, trigger the crash in Pidgin and then upload that

clean `pidgin.RPT` file to the bug report you are submitting.

- The Microsoft Windows "Error Report" isn't useful to us in any way; make sure

you **do not** include it in the bug report.

pidgin/nest