IntelliJ: Debug Your Plugin

Dec 22, 2021
IntelliJ: Debug Your Plugin
  • IntelliJ: Debug your Plugin

    Guide to remote and local debugging with IntelliJ IDEA.

    Quick explanation what this is: Remote Debugging empowers you to stop the program at specific points to e.g. check the value of variables and quickly adjust them. It also makes it possible to change code without reloading / restarting the server. Not everything can be changed this way though.

    Thought I'd make a tutorial on how to remote debug using IntelliJ since there are no detailed, recent examples or tutorials. In this tutorial I will be using IntelliJ IDEA 15, however the process should be similar for other versions of the IDE. Please note this tutorial will work with both Windows and macOS.

    Stopped Server
    IntelliJ IDEA
    Project to Test/Use With
    < 3 Minutes

    Method 1: Spigot as a Debug Server

    Step 1 | Setting Up IntelliJ

    • Navigate to Run > Edit Configurations


    • You should now see the window below, click + (top left) > Remote


    • You have created a new configuration! Now we need to set it up. Give it a name, set the port (I've used 5005) and copy the text from the top text box (you can see I have highlighted it below) we will be using it to set up the server. Hit Apply > OK to save and close this window.


    * Make sure "Search sources using module's classpath" is set to your project or it will not work!*

    Step 2 | Editing the Server Startup Command

    • Now we need to add the arguments to the startup script. Open the start_server.command or start_server.bat and paste the following arguments before the '-jar spigot.jar' on the same line. We have just copied these from the Edit Configurations window in the previous step.

    Code (Text):
    • This is how mine looked after the addition, yours should look similar.

    Code (Text):
    java -Xmx2G -Xms2G -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 -jar ./spigot.jar
    • Save the file and start your server. When it has loaded up fully move onto the next step.

    Step 3 | Connecting IntelliJ and Compiling

    • Take a look in the top right-hand corner of IntelliJ and you should see the name of the new configuration you have just made, and a few buttons like as pictured.

    (NB. If your config isn't selected, please select it from the dropdown)
    • Hit the green Bug button to connect, the following console will popup in the bottom corner of your screen and show you whether if it has been successful. To apply any changes hit the hammer. To set breaking points just click next to the line numbers. The program will stop there.

    • That's it! You are now connected, all you have to do is press the button to the left of the configuration name (pictured in the first picture of this step, highlighted with red square) to make and reload the project including your changes.
    • The first time you do this, a message box pops up asking you to confirm you want to make the changes. It will be easiest if you tick 'Don't show this message again' to speed the process up.
    *If you are using Maven this will still work, but comment out any relocations in your pom.xml when debugging*

    I hope you find this as useful as I do. If you need help make a post on the forum and if I see it I will try to help you out,

    - xtechgamer735

    IMPORTANT: The default value of timeout-time in spigot.yml is 60. This causes your server to time out if you resume the thread after 60 seconds. To prevent your server from constantly timing out while debugging, set timeout-time to a large number.

    The client will still time out after 30 seconds, so if someone knows how to overcome this please edit this wiki!

    Method 2: IDE as Debug Server (Remote)

    If you need to debug your plugin at server startup time (for example, plugin onLoad() or onEnable() methods) you may want to use IDE as Debug Server instead of spigot server itself.

    Steps are almost the same. Therefore, I will describe only differ of steps from method 1.

    Step 1 | Setting Up IntelliJ

    In debug configuration that you've created, change "Debugger mode" from "Attach to remote JVM" to "Listen to remote JVM". Then you can copy "Command line arguments for remote JVM", but it's contains optional params, which you need to setup manually. So, we will use jvm arguments from first method with one small modification, which described in step 2.


    Step 2 | Editing the Server Startup Command

    Now you need to modify server=y option of agentlib, it must be server=n. Full argument looks like:

    Code (Text):

    Step 3 | Connecting IntelliJ

    With this method, IDE is a Debug Server and spigot server is a Debug Client, therefore, you need first start debugging in IDE, and only then start spigot server.

    * If you don't do this in right sequence, you will see something like this in server terminal:

    Code (Text):

    ERROR: transport error 202: connect failed: Connection refused
    ERROR: JDWP Transport dt_socket failed to initialize, TRANSPORT_INIT(510)
    JDWP exit error AGENT_ERROR_TRANSPORT_INIT(197): No transports initialized [debugInit.c:750]

    You will make the same process. however. it will look like this:
    Code (Text):
    It will not work. to get it working replace the "*:" In the address so it looks like:
    Code (Text):
    It will work then!

    Method 3: IDE as Debug Server (Local)

    The steps are very similar to the methods above. With this method you will be able to run your server and debug your plugin directly from your IDE with no restarts (and maven packaging) required between changes!

    Step 1 | Setting Up The Server Configuration
    • Instead of Remote we will use the JAR Application option.


    • Now all we need to do is fill the fields like so:
      • Path to JAR: the path to your server.jar
      • VM options: your java arguments (to skip the 20s delay on older versions add this argument -DIReallyKnowWhatIAmDoingISwear)
      • Program arguments: your server arguments (usually just nogui)
      • Working directory: the path to your server folder
      • JRE: leave this empty or Default if your project java version is already set up. Otherwise, depending on your minecraft server version:
        • 1.16 and older - java 8
        • 1.17 and newer - java 16
    • Now your configuration should look something like this.


    • Hit Apply and make sure you have the new configuration selected.
    • You can now run your server directly using the debug option!


    • By default your console will be located in the Debug window next to the Debugger tab, but if you cant find it, enable it from the layout settings button on right


    Code (Text):
    WARN Unable to instantiate org.fusesource.jansi.WindowsAnsiOutputStream
    * Indicates that colors are not supported in the console, add -Dlog4j.skipJansi=true to the java arguments to disable it

    Step 2 | Debugging the plugin
  • Loading...
  • Loading...