Skip to content

How to debug JVM crashes

Jump to bottom
Emy 💜 edited this page Dec 12, 2025 · 4 revisions

JVM crashes, not to be confused with regular crashes, happen whenever the Java Virtual Machine encounters a catastrophic issue such as buffer over/underflows and null pointer dereferencing. These issues are extremely hard to debug without specialized JVM builds and tools. This guide assume that you are under Linux.

This guide aims to provide an easy step-by-step guide for non technical users to:

  • Compile a custom OpenJDK version with 'fastdebug'
  • Install and use the GNU Debugger
  • Install a custom gdb dashboard for ease of use

Compiling OpenJDK with fastdebug

The fastdebug option when compiling OpenJDK adds the debugging information to the java runtime while keeping all the optimization. You can read more about it in the OpenJDK source code

  1. Get the complete source code: git clone https://github.com/openjdk/jdk21

  2. Run configure: bash configure --with-debug-level=fastdebug

If configure fails due to missing dependencies (to either the toolchain, build tools, external libraries or the boot JDK), most of the time it prints a suggestion on how to resolve the situation on your platform. Follow the instructions, and try running bash configure again.

  1. Run make: make images

  2. Verify your newly built JDK: ./build/*/images/jdk/bin/java -version

After a while, you should now have a complete build of the java runtime with fastdebug enabled.

Install the GNU Debugger

The installation process is different for each platform. I have added various link for different popular OSes.

Arch:

sudo pacman -Syu gdb

Debian:

sudo apt-get install gdb

Fedora:

sudo dnf install gdb

Install gdb-dashboard

GDB-Dashboard is a standalone .gdbinit config file that adds a modular visual interface for gdb. This is our recommended config for debugging the JVM. Place the following in ~/.gdbinit.d/init:

dashboard -layout assembly breakpoints expressions history memory registers source stack !threads variables
dashboard -style compact_values False
dashboard -style max_value_length 200
dashboard variables -style compact False
dashboard source -style highlight-line True

handle SIGSEGV noprint pass # Ignore various segmentation faults thrown by the JVM for reasons that are unknown to me

set debuginfod enabled on # Use debuginfod to download various debugging symbols

Prepare the game launch

You first need to setup the development environment

In order to launch the game through GDB, you first have to launch the game with the following command:

gradle runClient --info 2>&1 | grep 'Command:'

This will generate the necessary files for Fabric to work and give you the command to use in gdb.

Run the game with GDB

After everything has been setup correctly, you should be able to run Lambda through gdb with this command followed with the previous step with your custom opengjdk build: gdb --args <the command goes here>

When you are ready, you can type run to begin the execution. Do not be surprised if it makes multiple minutes for the game to launch.

Exporting the program state

TODO

Clone this wiki locally