Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
Julia Debugging Procedures

Julia Debugging Procedures

So you managed to break Julia. Congratulations! Collected here are some general procedures you can undergo for common symptoms encountered when something goes awry. Including the information from these debugging steps can greatly help the maintainers when tracking down a segfault or trying to figure out why your script is running slower than expected.

If you've been directed to this page, find the symptom that best matches what you're experiencing and follow the instructions to generate the debugging information requested. Table of symptoms:

Version/Environment info

No matter the error, we will always need to know what version of julia you are running, and may ask you to update to the latest version if your version is not an official release and is more than a month old. When julia first starts up, a header is printed out with a version number and date. If your version is 0.2.0 or higher, please include the output of versioninfo() in any report you create:

julia> versioninfo()
Julia Version 0.2.0-prerelease+3002
Commit 35c12bd 2013-08-06 13:13:03 UTC
Platform Info:
  System: Linux (x86_64-linux-gnu)
  LIBM: libopenlibm

If your version is less than 0.2.0, please include the version of Julia from the header, along with your OS name and version. If julia does not start up, a coarser estimate of the version information will suffice. (E.g. the version from the distribution package you installed from such as apt-get, or the output of git log -1 if compiling from source)

Segfaults during bootstrap (sysimg.jl)

Segfaults toward the end of the make process of building julia are a common symptom of something going wrong while julia is preparsing the corpus of code in the base/ folder. Many factors can contribute toward this process dying unexpectedly, however it is as often as not due to an error in the C-code portion of julia, and as such must typically be debugged with a debug build inside of gdb. Explicitly:

Create a debug build of julia:

$ cd <julia_root>
$ make debug

Note that this process will likely fail with the same error as a normal make incantation, however this will create a debug executable that will offer gdb the debugging symbols needed to get accurate backtraces. Next, manually run the bootstrap process inside of gdb:

$ cd base/
$ gdb -x ../contrib/debug_bootstrap.gdb

This will start gdb, attempt to run the bootstrap process using the debug build of julia, and print out a backtrace if (when) it segfaults. You may need to hit <enter> a few times to get the full backtrace. Create a gist with the backtrace, the version information, and any other pertinent information you can think of and open a new issue on Github with a link to the gist.

Segfaults when running a script

The procedure is very similar to segfaulting during the bootstrap phase. Create a debug build of Julia, and run your script inside of a debugged julia process:

$ cd <julia_root>
$ make debug
$ gdb --args usr/bin/julia-debug-readline <path_to_your_script>

Note that gdb will sit there, waiting for instructions. Type r to run the process, and bt to generate a backtrace once it segfaults:

(gdb) r
Starting program: /home/sabae/src/julia/usr/bin/julia-debug-readline ./test.jl
(gdb) bt

Create a gist with the backtrace, the version information, and any other pertinent information you can think of and open a new issue on Github with a link to the gist.

Errors during julia startup

Occasionally errors occur during julia's startup process (especially when using binary distributions, as opposed to compiling from source) such as the following:

$ julia
exec: error -5

These errors typically indicate something is not getting loaded properly very early on in the bootup phase, and our best bet in determining what's going wrong is to use external tools to audit the disk activity of the julia process:

  • On Linux, use strace:
$ strace julia
  • On OSX, use dtruss:
$ dtruss -f julia

Create a gist with the strace/dtruss ouput, the version information, and any other pertinent information and open a new issue on Github with a link to the gist.

Slow script performance

Before asking for help speeding up a slow script, it can be very useful to determine for yourself which areas of your code are taking up the most CPU time to get an idea as to what is perhaps an algorithmic problem versus a problem in the standard library or compiler of julia. From version 0.2.0 onward, the standard library includes a profiler which can be used to determine which areas of your code (including C functions!) are requiring the most CPU time. We defer to the excellent documentation on the profiler for instruction on its usage.

Another tool in the arsenal against slow performance is the Performance Tips section in the manual, which contains many programming patterns to avoid when attempting to eke the last cycle of performance out of a julia script.

Finally, when all else fails, and a script is performing much worse than should be expected, please create a gist with the simplest possible script that exhibits the problems you are experiencing, the version information, and any other pertinent information you can think of and open a new issue on Github with a link to the gist.


A few terms have been used as shorthand in this guide:

  • <julia_root> refers to the root directory of the julia source tree; e.g. it should contain folders such as base, deps, src, test, etc.....

vtjnash commented Aug 8, 2013

This looks much better than mine. However, since I tried to focus on the Windows-specific details, I thought it might still be helpful to cross-link this here:

How about merging these two and putting them into the manual?


staticfloat commented Aug 10, 2013

I'm happy to merge the two; do we really want to ask people to debug windows builds in wine though? That seems like something only people who are rather familiar with gdb, etc... would do.

timholy commented Nov 2, 2013

+1 for getting this excellent writeup into the manual somewhere.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment