# Advanced debugging of MRtrix3 binaries

**URL:** <https://community.mrtrix.org/t/advanced-debugging-of-mrtrix3-binaries/2555>\
**Category:** Wiki\
**Tags:** troubleshooting, error\
**Created:** [May 23, 2019, 6:18pm UTC](https://community.mrtrix.org/t/advanced-debugging-of-mrtrix3-binaries/2555 "2019-05-23T18:18:57Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![rsmith](https://community.mrtrix.org/user_avatar/community.mrtrix.org/rsmith/32/2672_2.png) [@rsmith](https://community.mrtrix.org/u/rsmith)\
**Post date:** [May 23, 2019, 6:18pm UTC](https://community.mrtrix.org/t/advanced-debugging-of-mrtrix3-binaries/2555/1 "2019-05-23T18:18:57Z")

</div>

On rare occasions, a user may encounter a critical error (e.g. “Segmentation fault”) within an _MRtrix3_ command that does not give sufficient information to identify the cause of the problem, and that the developers are unable to reproduce. In these cases, we will often ask to be provided with example data that can consistently reproduce the problem in order to localise the issue. An alternative is for the user  
to perform an initial debugging experiment, and provide us with the resulting information. The instructions for doing so are below.

1. If required, install “`gdb`”: the [GNU Debugging Tool](https://www.gnu.org/software/gdb/) (specific instructions for this installation will depend on your particular operating system). If using macOS, the equivalent debugging tool is “`lldb`”, which comes with the installation of Xcode.

2. _Make sure_ you are using the most up-to-date _MRtrix3_ code!  
(`git pull`)

3. Configure and compile _MRtrix3_ in debug mode:

4. Execute the problematic command within `gdb`:

5. If running on Windows, once `gdb` has loaded, type the following into the terminal:

6. At the `gdb` or `lldb` terminal, type “`r`” and hit ENTER to run the command.

7. If an error is encountered, `gdb` or `lldb` will print error information, and then provide a terminal with “`(gdb)`” or “`(lldb)`” shown on the left hand side. Type “`bt`” and hit ENTER: This stands for “backtrace”, and will print details on the internal code that was running when the problem occurred.

8. Copy all of the raw text, from the command you ran in instruction 3 all the way down to the bottom of the backtrace details, and post it to the location where the issue was first raised (either here on the community forum, or in the [Issue tracker](https://github.com/MRtrix3/mrtrix3/issues) for the GitHub repository.

* * *

If `gdb` or `lldb` does not report any error, it is possible that a memory error is occurring, but even the debug version of the software is not performing the necessary checks to detect it. If this is the case, you can also try using [Valgrind](http://valgrind.org/), which performs a more exhaustive check for memory faults (and correspondingly, the command will run exceptionally slowly):

```auto
$ valgrind bin/command (arguments) (-options)

```

(replace “`command`” with the name of the command you wish to run).

* * *

When you have finished debugging, restore your default _MRtrix3_ compilation:

```nohighlight
$ ./build select default

```

Binaries compiled in debug mode run considerably slower than those compiled using the default settings (even if not running within `gdb` or `lldb`), due to the inclusion of various symbols that assist in debugging and the removal of various optimisations. Therefore it’s best to restore the default configuration of _MRtrix3_ for your ongoing use of the software.