# How to debug Vassal **URL:** https://forum.vassalengine.org/t/how-to-debug-vassal/90403 **Category:** Documentation **Created:** [August 10, 2026, 8:39pm UTC](https://forum.vassalengine.org/t/how-to-debug-vassal/90403 "2026-08-10T20:39:49Z") **Posts on this page:** 1 **Page:** 1
### Author: ![cholmcc](https://forum.vassalengine.org/user_avatar/forum.vassalengine.org/cholmcc/32/8319_2.png) [@cholmcc](https://forum.vassalengine.org/u/cholmcc) #### Post date: [August 10, 2026, 8:39pm UTC](https://forum.vassalengine.org/t/how-to-debug-vassal/90403/1 "2026-08-10T20:39:49Z")
## Introduction Sometimes, Vassal may error out on some exception, or similar, and in that case, it can be useful to run Vassal through a [debugger](https://en.wikipedia.org/wiki/Debugger). Running an application in a debugger allows one to query the state of the application and thus pin down the problem that caused the error. **Important** : Running an application in a debugger is not for the faint-of-heart. Only attempt this if you are willing to put in the work yourself, or you already have experience with such as task. ## Requirements ### Java Developement Kit (JDK) You will need a _full_ Java Development Kit (JDK) to run the Java debugger `jdb`. #### ![windows](https://forum.vassalengine.org/uploads/default/original/2X/6/6493154fc0bdf2bbf13fe4264cfbd26389f67e37.png) Windows Vassal comes with its own Java Runtime Environment (JRE) - but not a full JDK - on Windows. You therefore need to download and install a JDK, if you do not have one already. You should pick a JDK that corresponds to the JRE shipped with Vassal (see the relevant information in the [`errorLog`](https://forum.vassalengine.org/t/how-to-report-problems/84989#p-168118-error-log-9)). For example, to get the JDK corresponding to the Temurin JRE 26, go to [Temurin download page](https://adoptium.net/en-GB/temurin/releases) and select the appropriate version. Follow the installation instructions to set up the JDK. #### ![macosx](https://forum.vassalengine.org/uploads/default/original/2X/c/c24d21f1dbd9387b7973e19633ee3e5e1f63f213.png) MacOS Vassal comes with its own Java Runtime Environment (JRE) - but not a full JDK - on Windows. You therefore need to download and install a JDK, if you do not have one already. You should pick a JDK that corresponds to the JRE shipped with Vassal (see the relevant information in the [`errorLog`](https://forum.vassalengine.org/t/how-to-report-problems/84989#p-168118-error-log-9)). For example, to get the JDK corresponding to the Temurin JRE 26, go to [Temurin download page](https://adoptium.net/en-GB/temurin/releases) and select the appropriate version. Follow the installation instructions to set up the JDK. #### ![linux](https://forum.vassalengine.org/uploads/default/original/2X/d/d5872a3245eb562d6cb33880d5f4fdf3366107fc.png) Linux Chances are you already have a full JDK installed. If not, see below ##### ![debian](https://forum.vassalengine.org/uploads/default/original/2X/6/6a99d88a27284e1728eedc25c9de3fd8b00df8da.png) Debian and derivatives ```auto $ sudo apt install default-jdk ``` ##### ![redhat](https://forum.vassalengine.org/uploads/default/original/2X/8/8f4dec2204e54c851dc1fbfa49633bd2420c7dc7.png) Redhat and derivatives One of ```auto $ sudo dnf install java-latest-openjdk $ sudo yum install java-latest-openjdk ``` ##### ![arch](https://forum.vassalengine.org/uploads/default/original/2X/2/24d281f3935b3e03c31ff63ba05a4e23113d7107.png) Arch Linux and derivatives ```Shell $ sudo pacman -S --needed jre-openjdk ``` ##### ![gentoo](https://forum.vassalengine.org/uploads/default/original/2X/0/08febe8df44d8351ce082ac14d609e663576b428.png) Gentoo and derivatives ```Shell $ sudo emerge --ask --oneshot virtual/jre ``` ##### ![other](https://forum.vassalengine.org/uploads/default/original/2X/5/5181e0520049e90c5ff79130660212769bae473c.png) Other distributions Please refer to your distribution’s documentation. ### Vassal source code The best way to get the Vassal source code is to clone it from [Github](https://github.com/vassalengine/vassal). To do that, you will need the application [Git](https://git-scm.com/). Then, do ```auto $ git clone https://github.com/vassalengine/vassal.git $ cd vassal $ git checkout 3.7.26 ``` to point the sources at the 3.7.26 release (adjust for the release of Vassal that you use). An alternative, is to download the source from the Vassal [release assets](https://github.com/vassalengine/vassal/releases) (Source code `.zip` or `.tar.gz`) and unpack them somewhere. ## Assumptions Suppose you find there’s some problem that pops up when you use the module `Module.vmod`. Now, also assume that you downloaded the Vassal sources to a directory _a la_ | OS | Vassal source directory | | --- | --- | | ![windows](https://forum.vassalengine.org/uploads/default/original/2X/6/6493154fc0bdf2bbf13fe4264cfbd26389f67e37.png) | `C:\Users\user\Documents\vassal` | | ![macosx](https://forum.vassalengine.org/uploads/default/original/2X/c/c24d21f1dbd9387b7973e19633ee3e5e1f63f213.png) | `/home/user/Documents/vassal` | | ![linux](https://forum.vassalengine.org/uploads/default/original/2X/d/d5872a3245eb562d6cb33880d5f4fdf3366107fc.png) | `/home/user/Documents/vassal` | Also assume that you have Vassal installed as | OS | Vassal installation directory | | --- | --- | | ![windows](https://forum.vassalengine.org/uploads/default/original/2X/6/6493154fc0bdf2bbf13fe4264cfbd26389f67e37.png) | `C:\Program Files\VASSAL` | | ![macosx](https://forum.vassalengine.org/uploads/default/original/2X/c/c24d21f1dbd9387b7973e19633ee3e5e1f63f213.png) | `/Applications/VASSAL.app` | | ![linux](https://forum.vassalengine.org/uploads/default/original/2X/d/d5872a3245eb562d6cb33880d5f4fdf3366107fc.png) | `/usr/share/vassal` | ## Launch Vassal in the debugger When you run Vassal normally, it starts the _Module Manger_. When you from that module manager start or edit a module, then Vassal will spawn another process and execute a different entry point (`VASSAL.launch.Player` or `VASSAL.launch.Editor`, respectively). That process that we are most likely interested in, is the child process, so we need to by-pass the module manger and go straight at the child process. ### ![windows](https://forum.vassalengine.org/uploads/default/original/2X/6/6493154fc0bdf2bbf13fe4264cfbd26389f67e37.png) Windows Open a command prompt (`cmd` or `PowerShell`), and run ```auto $ jdb -sourcepath C:\Users\user\Documents\vassal\vassal-app\src/main\java -cp C:\Program Files\VASSAL\lib\Vengine.jar VASSAL.launch.Player --load Module.vmod ``` ### ![macosx](https://forum.vassalengine.org/uploads/default/original/2X/c/c24d21f1dbd9387b7973e19633ee3e5e1f63f213.png) MacOS Launch a _Terminal_ and do ```auto $ jdb -sourcepath /home/user/Documents/vassal/vassal-app/src/main/java -cp /Applications/VASSAL.app/Contents/Resources/Java/Vengine.jar VASSAL.launch.Player --load Module.vmod ``` ### ![linux](https://forum.vassalengine.org/uploads/default/original/2X/d/d5872a3245eb562d6cb33880d5f4fdf3366107fc.png) Linux Open some terminal and do ```auto $ VASSAL.sh --debug --source /home/user/Documents/vassal/vassal-app/src/main/java --load Module.vmod ``` ## Set-up break points and run Vassal The will start the debugger, but Vassal isn’t running yet. If you found, when looking in the `errorLog` that the exception `java.lang.FooException` was thrown - for example, then you can make sure you will catch that in the debugger with ```auto jdb$ catch all java.long.FooException ``` If you want to set a break-point in some method - say `VASSAL.counters.FreeRotator.draw`, then you can do ```auto jdb$ stop at VASSAL.counters.FreeRotator.draw ``` To start Vassal, do ```auto jdb$ run ``` Once the application is up and running, do the interactions that will trigger the problem. The debugger should break at that point and pause the application. Use the `help` command in `jdb` to get information about what you can do. For example `print`, `list`, and so on. See also the [Oracle (short) `jdb` manual](https://docs.oracle.com/en/java/javase/17/docs/specs/man/jdb.html) and countless other resources on the World-Wide-Web.