How to remotely debug Java application in IntelliJ

This tutorial will show you how to debug your JAR or WAR file in IntelliJ IDEA remotely and gives you hints on developing new features through the application stack.


Let me give you a few tips few prerequisites necessary for smooth and successful remote debug.

Debug same version as on the remote server

To debug a remote server-side application in your IntelliJ IDEA, you need to have the same version of your application or component on your side in IntelliJ IDEA as on the server-side. To do so, you shall first finish all the changes you want to test on the remote server. Then build your application and deploy it to the remote server. Only then you should run remote debug mode against your remote environment.

In a reverse way, if you can not change what is on the server, rebase your code repository on the commit of JAR or WAR file set on the server. Build the application with the build tool of your choice (Maven/Gradle), and only then you are can remotely debug.

Don’t make any additional changes before remote debug

Writing the following note might be unnecessary, yet it is better to say it loud as a reminder. If you make any changes in your code between deployment on the remote server and running the application in remote debug mode, remote debug will not work. Even on the slightest change, remote debug will not decompile your breakpoint on the desired code line because Java bytecode will be different.

Build faster without tests

Just a tip, for a fast Maven build you can use mvn clean install -DskipTests.

For more information regarding running Maven build without tests check the article about how to build Java application with Maven without running tests.

Coordination your work with the rest of the team

If you are working in a team and want to be a good team player (or working on something very sensitive), let your teammates know you want to deploy and remotely debug your application. Ask publicly your colleagues, e.g. in Slack, if it is OK to occupy test instance for a while. Coordinate your debugging according to the response or according to your organization policy. Let’s say, if nobody responds in 15 minutes, you are clear to go.

Adjustment of other parts

For more complex change trough the stack, it might be necessary to change and adjust different system parts. E.g., if you are working on the monolith, you might need to adjust the front-end client for testing purposes. In other cases, it might be necessary to change the database.

Adjusting other parts of the system might be necessary for the system to work, and you be able to test changes through the whole stack.

In every case, do not forget to clean after yourself when leaving (check the last point of this tutorial for more info).

1. In IntelliJ IDEA, create new Run/Debug Configuration for Remote JVM Debug

Remote Debug in IntelliJ IDEA
Example of setup in IntelliJ IDEA

Host and port configurations can be changed based on the remote environment you want to debug.

If you are using a multi-module project, select a module in Use module classpath.

2. Run remote debug configuration in debug mode

Connecting to the host should be nearly instant. Now all you need to do is place the breakpoints in your code. When the application code executes in a connected environment on the line you set the breakpoint, the breakpoint should be hit, and stack trace should be shown in your IntelliJ IDEA. That is it, simple as that.

3. Do not forget to close your debug session

Do not forget to close your debug session. Unclosed sessions cause port/socket-exhaustion and lead to server restart. Also, try not to keep the session open for long and stuck on the breakpoint for too long. TimeOutException and other exceptions might occur which will lead to further server resource consumption.

4. Clean up

After successful testing, it might be necessary to return the testing environment to the original state. Build your current master/develop branch and place it back in the test environment. If your colleagues do not notice that the testing environment does not work as it should, it means you made a good job cleaning after yourself and placing the project back in a stable state.

If you are on your own, I highly recommend you to clean after yourself too. You will never know when you will need to return to your projects again, and you might not remember in that time why the testing environment looks like it is.

This entry was posted in Tips & tricks and tagged , , , , , , , , , , , , , , . Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.