Reporting and analyzing crashes (segfaults)

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:

• Segfaults during bootstrap (sysimg.jl)
• Segfaults when running a script
• Errors during Julia startup
• Other generic segfaults or unreachables reached

Version/Environment info

No matter the error, we will always need to know what version of Julia you are running. When Julia first starts up, a header is printed out with a version number and date. Please also include the output ofversioninfo() (exported from theInteractiveUtils standard library) in any report you create:

julia> using InteractiveUtils
julia> versioninfo()Julia Version 1.11.6Commit 9615af0f269 (2025-07-09 12:58 UTC)Build Info:  Official https://julialang.org/ releasePlatform Info:  OS: Linux (x86_64-linux-gnu)  CPU: 128 × AMD EPYC 7502 32-Core Processor  WORD_SIZE: 64  LLVM: libLLVM-16.0.6 (ORCJIT, znver2)Threads: 1 default, 0 interactive, 1 GC (on 128 virtual cores)Environment:  JULIA_DEPOT_PATH = /cache/julia-buildkite-plugin/depots/018de947-b86e-4a96-a198-061223670bea  JULIA_CPU_THREADS = 128  JULIA_NUM_THREADS = 1

Segfaults during bootstrap (sysimg.jl)

Segfaults toward the end of themake process of building Julia are a common symptom of something going wrong while Julia is preparsing the corpus of code in thebase/ 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 ofgdb. 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 normalmake incantation, however this will create a debug executable that will offergdb the debugging symbols needed to get accurate backtraces. Next, manually run the bootstrap process inside ofgdb:

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

This will startgdb, 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 agist with the backtrace, theversion info, and any other pertinent information you can think of and open a newissue on Github with a link to the gist.

Segfaults when running a script

The procedure is very similar toSegfaults during bootstrap (sysimg.jl). 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 <path_to_your_script>

Note thatgdb will sit there, waiting for instructions. Typer to run the process, andbt to generate a backtrace once it segfaults:

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

Create agist with the backtrace, theversion info, and any other pertinent information you can think of and open a newissue 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:

$ juliaexec: 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 thejulia process:

• On Linux, usestrace:

  $ strace julia

• On OSX, usedtruss:

  $ dtruss -f julia

Create agist with thestrace/dtruss output, theversion info, and any other pertinent information and open a newissue on Github with a link to the gist.

Other generic segfaults or unreachables reached

As mentioned elsewhere,julia has good integration withrr for generating traces; this includes, on Linux, the ability to automatically runjulia underrr and share the trace after a crash. This can be immensely helpful when debugging such crashes and is strongly encouraged when reporting crash issues to the JuliaLang/julia repo. To runjulia underrr automatically, do:

julia --bug-report=rr

To generate therr trace locally, but not share, you can do:

julia --bug-report=rr-local

Note that this is only works on Linux. The blog post onTime Travelling Bug Reporting has many more details.

Glossary

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 asbase,deps,src,test, etc.....