Informing about failures (emergency terminations) and their analysis
This article describes some common procedures that can be performed for common symptoms that occur when something goes wrong in Julia’s work. Including information from these debugging steps in the report can greatly help maintenance professionals when tracking an emergency shutdown or trying to figure out why your script is running slower than expected.
If you have been directed to this page, find the symptom that best matches the situation and follow the instructions to create the requested debugging information. Tables of symptoms:
Version or environment information
Regardless of the error, we always need to know which version of Julia you are using. The first time Julia is launched, a header with a version number and date is displayed. In the report you are creating, include the output of the versioninfo() function (exported from the standard library InteractiveUtils).
julia> using InteractiveUtils
julia> versioninfo()
Julia Version 1.11.3
Commit d63adeda50d (2025-01-21 19:42 UTC)
Build Info:
Official https://julialang.org/ release
Platform Info:
OS: Linux (x86_64-linux-gnu)
CPU: 4 × 11th Gen Intel(R) Core(TM) i3-1115G4 @ 3.00GHz
WORD_SIZE: 64
LLVM: libLLVM-16.0.6 (ORCJIT, tigerlake)
Threads: 1 default, 0 interactive, 1 GC (on 4 virtual cores)Crashes during boot up (sysimg.jl)
Failures at the end of the make process of the Julia build are a common symptom that something went wrong during the preliminary analysis of a large amount of code in the 'base/` folder. Many factors can contribute to the unexpected completion of this process, but most often it is associated with an error in part of the C code in Julia, as a result of which, as a rule, it is necessary to perform a debug build inside gdb. Follow these steps.
Create a Julia debug build.
$ cd <julia_root> $ make debug
Please note that this process will most likely end with the same error as the usual make incantation, however, a debug executable file will be created that will offer 'gdb' the debugging symbols necessary to obtain an accurate backtrace. Then manually start the bootstrapping process inside `gdb'.
$ cd base/ $ gdb -x ../contrib/debug_bootstrap.gdb
gdb will be launched, an attempt will be made to start the bootstrap process using the Julia debug build usage, and a backtrace will be output if (when) an emergency shutdown occurs. You may need to press the <enter> key several times to get a complete backtrace. Create https://gist .github.com [gist] with backtracking, version information and any other necessary information that you want to provide, and open a new one https://github.com/JuliaLang/julia/issues ?q=is%3Aopen[the problem] on the GitHub site with a link to gist.
Crashes during script execution
This procedure is very similar to the one described in the section Segfaults during bootstrap (sysimg.jl). Create a Julia debug build and run the script inside the Julia process being debugged.
$ cd <julia_root> $ make debug $ gdb --args usr/bin/julia-debug <path_to_your_script>
Note that 'gdb` will be there and waiting for instructions. Type r to start the process, and `bt' to generate a backtrace when it crashes.
(gdb) r Starting program: /home/sabae/src/julia/usr/bin/julia-debug ./test.jl ... (gdb) bt
Create https://gist .github.com [gist] with backtracking, version information and any other necessary information that you want to provide, and open a new one https://github.com/JuliaLang/julia/issues ?q=is%3Aopen[the problem] on the GitHub site with a link to gist.
Errors during Julia startup
Sometimes errors occur during the launch of Julia (especially when usage of binary distributions, as opposed to compilation from source code), for example:
$ julia
exec: error -5These errors usually indicate that something is not loading properly at the earliest stage of the download. The best way to identify the problem is usage of external tools to audit the operation of the disk in the julia process.
-
On Linux, use `strace'.
$ strace julia
-
On OSX, use
dtruss:$ dtruss -f julia
Create https://gist .github.com [gist] with strace'/ `dtruss output, version information and any other necessary information, and open a new one https://github.com/JuliaLang/julia/issues ?q=is%3Aopen[the problem] on the GitHub site with a link to gist.
Other common errors or unavailability
As mentioned, julia integrates well with rr to generate traces. On Linux, this includes the ability to automatically run julia in rr and exchange traces after a crash. This can be very useful when debugging such failures and is highly recommended to do when reporting failures in the JuliaLang or julia repository. To automatically run julia in `rr', do the following.
julia --bug-report=rrTo generate an rr trace locally but not share it, you can do the following.
julia --bug-report=rr-localNote that this only works on Linux. Details can be found in the blog post https://julialang.org/blog/2020/05/rr /[Time Traveling Bug Reporting].