1. Introduction
Debugging is one of the most important tools for writing software.
In this tutorial, we’ll review some of the ways in which we can debug Spring applications.
We’ll also demonstrate how Spring Boot, traditional application servers, and IDEs simplify this.
2. Java Debug Args
First, let’s look at what Java gives us out of the box.
By default, the JVM doesn’t enable debugging. This is because debugging creates additional overhead inside the JVM. It can also be a security concern for applications that are publicly accessible.
Therefore, debugging should only be performed during development, and never on production systems.
Before we can attach a debugger, we must first configure the JVM to allow debugging. We’ll do this by setting a command line argument for the JVM:
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000
Let’s break down what each of these values means:
-agentlib:jdwp
This enables the Java Debug Wire Protocol (JDWP) agent inside the JVM. This is the main command line argument that enables debugging.
transport=dt_socket
This uses a network socket for debug connections. Other options include Unix sockets and shared memory.
server=y
This listens for incoming debugger connections. When set to n, the process will try to connect to a debugger instead of waiting for incoming connections. Additional arguments are required when this is set to n.
suspend=n
This means don’t wait for a debug connection at startup. The application will start and run normally until a debugger is attached. When set to y, the process won’t start until a debugger is attached.
address=8000
This is the network port that the JVM will listen on for debug connections.
The values above are standard and will work for most use cases and operating systems. The JPDA connection guide covers all the possible values in more detail.
2.1. Binding Address on JDK9+
On JDK8 and below, setting the address property to port number only (address=8000 in the example above) means that the JVM listens on all available IP addresses. Therefore, remote connections are available out of the box.
This has changed in JDK9+ due to security reasons. Currently, the default setup allows localhost connections only.
This means that if we want to make remote connections available, we need to either prefix the port number with the hostname, address=myhost:8000, or use an asterisk to listen on all available IP addresses, address=*:8000.
3. Spring Boot Applications
There are several ways to start Spring Boot applications. The simplest way is from the command line using the java command with the -jar option.
To enable debugging, we simply add the debug argument using the -D option:
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000 -jar myapp.jar
With Maven, we can use the provided run goal to start our application with debugging enabled:
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000"
Similarly, with Gradle, we can use the bootRun task. First, we must update the build.gradle file to ensure Gradle passes command line arguments to the JVM:
bootRun {
systemProperties = System.properties
}
Now we can execute the bootRun task:
gradle bootRun -Dagentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000
4. Application Servers
While Spring Boot has become very popular in recent years, traditional application servers are still quite prevalent in modern software architectures. In this section, we’ll look at how to enable debug for some of the more popular applications servers.
Most application servers provide a script for starting and stopping applications. Enabling debug is typically just a matter of adding additional arguments to this script and/or setting additional environment variables.
4.1. Tomcat
The startup script for Tomcat is named catalina.sh (catalina.bat on Windows). To start a Tomcat server with debug enabled, we can prepend jpda to the arguments:
catalina.sh jpda start
The default debug arguments will use a network socket listening on port 8000 with suspend=n. These can be changed by setting one or more of the following environment variables: JPDA_TRANSPORT, JPDA_ADDRESS, and JPDA_SUSPEND.
We can also get full control of the debug arguments by setting JPDA_OPTS. When this variable is set, it takes precedence over the other JPDA variables. Thus, it must be a complete debug argument for the JVM.
4.2. Wildfly
The startup script for Wildfly is stand-alone.sh. To start a Wildfly server with debug enabled, we can add –debug.
The default debug mode uses a network listener on port 8787 with suspend=n. We can override the port by specifying it after the –debug argument.
For more control over the debug argument, we can just add the complete debug arguments to the JAVA_OPTS environment variable.
4.3. Weblogic
The startup script for Weblogic is startWeblogic.sh. To start a Weblogic server with debug enabled, we can set the environment variable debugFlag to true.
The default debug mode uses a network listener on port 8453 with suspend=n. We can override the port by setting the DEBUG_PORT environment variable.
For more control over the debug argument, we can just add the complete debug arguments to the JAVA_OPTIONS environment variable.
The latest versions of Weblogic also provide a Maven plugin to start and stop servers. This plugin will honor the same environment variables as the startup script.
4.4. Glassfish
The startup script for Glassfish is asadmin. To start a Glassfish server with debug enabled, we have to use –debug:
asadmin start-domain --debug
The default debug mode uses a network listener on port 9009 with suspend=n.
4.5. Jetty
The Jetty application server doesn’t come with a startup script. Instead, Jetty servers are started using the java command.
Thus, enabling debugging is as simple as adding the standard JVM command line arguments.
5. Debugging From an IDE
Now that we’ve seen how to enable debugging in various application types, let’s look at connecting a debugger.
Every modern IDE offers debugging support. This includes both the ability to start a new process with debugging enabled, as well as the ability to debug an already running process.
5.1. IntelliJ
IntelliJ offers first-class support for Spring and Spring Boot applications. Debugging is as simple as navigating to the class with the main method, right-clicking the triangle icon, and choosing Debug:
For Spring Boot applications, IntelliJ IDEA offers a dedicated plugin – Spring Debugger. The plugin allows us to see active loaded beans, actual property values, db connections, etc., right in the IDE. It is available for IDEA Ultimate starting from version 2025.2 and higher.
If a project contains multiple Spring Boot applications, IntelliJ will provide a Run Dashboard tool window. This window lets us debug multiple Spring Boot applications from a single place:
For applications using Tomcat or other web servers, we can create a custom configuration for debugging. Under Run > Edit Configurations, there are a number of templates for the most popular application servers:
Finally, IntelliJ makes it very easy to connect to any running process and debug it. As long as the application was started with the proper debug arguments, IntelliJ can connect to it, even if it’s on another host.
On the Run/Debug Configurations screen, the Remote template will let us configure how we want to attach to the already running application:
Note that IntelliJ only needs to know the hostname and debug port. As a convenience, it tells us the proper JVM command line arguments that should be used on the application that we want to debug.
5.2. Eclipse
The quickest way to debug a Spring Boot application in Eclipse is to right-click the main method from either the Package Explorer or Outline windows:
The default installation of Eclipse doesn’t support Spring or Spring Boot out of the box. However, there is a Spring Tools add-on available in the Eclipse Marketplace that provides Spring support comparable to IntelliJ.
Most notably, the add-on provides a Boot Dashboard that lets us manage multiple Spring Boot applications from a single place:
The add-on also provides a Spring Boot Run/Debug Configuration that allows us to customize the debug of a single Spring Boot application. This customized view is available from all the same places as the standard Java Application configuration.
To debug an already running process, either locally or on a remote host, we can use the Remote Java Application configuration:
6. Debugging With Docker
Debugging a Spring application inside a Docker container may require additional configuration. If the container is running locally, and isn’t using host network mode, then the debug port won’t be accessible outside the container.
There are several ways to expose the debug port in Docker.
We can use –expose with the docker run command:
docker run --expose 8000 mydockerimage
We can also add the EXPOSE directive to the Dockerfile:
EXPOSE 8000
Or, if we’re using Docker Compose, we can add it into the YAML:
expose:
- "8000"
7. Conclusion
In this article, we discussed how to enable debugging for any Java application.
By simply adding a single command line argument, we can easily debug any Java application.
We also learned that both Maven and Gradle, as well as most popular IDEs, all have specialized add-ons to make debugging Spring and Spring Boot applications even easier.
