Enabling Remote Debugging for Spring Boot Applications with JPDA

Preface

During a recent birthday party a friend complained about the endless bugs and project switches in his outsourcing job, which made us wonder whether we really need to start a local instance each time a problem occurs.

This article introduces remote debugging for Spring Boot applications and shows how to enable it.

What Is Remote Debugging?

Remote debugging means the server‑side program runs on a remote machine while you set breakpoints in the local source code (the local code must match the remote code). When a request reaches the remote server, you can observe its internal state from your local IDE.

In simple terms: you can debug server code in real time without launching the project locally.

Why Remote Debugging?

As projects grow, start‑up time increases; spending ten minutes to start an application just to fix a bug is inefficient.

What Is JPDA?

JPDA

(Java Platform Debugger Architecture) is the Java debugging framework. The core protocol is JDWP. In Java SE 5 and earlier the JVM used JVMPI; from Java SE 5 onward it uses JVMTI instead.

For Java SE 5 and earlier the debug command format is: java -Xdebug -Xrunjdwp:... For Java SE 5 and later the format is:

java -agentlib:jdwp=...

How to Enable Remote Debugging?

Since most projects now use Java SE 5 or later, we focus on the -agentlib:jdwp syntax.

The most common command is:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9093 -jar xxx.jar

The part before the first comma ( java -agentlib:jdwp=) is mandatory; the following options are optional and explained below.

transport

Specifies the communication protocol between the debugged application and the debugger. Options: dt_socket: socket connection (most common). dt_shmem: shared‑memory connection, limited to Windows.

server

Indicates whether the application acts as the debug server ( y) or client ( n, default).

suspend

Determines whether the application should block on start until a debugger attaches. Default is y (block). In most cases set to n to avoid blocking.

address

The port exposed for the debugger, default 8000. The port must be free and reachable from the IDE.

onthrow

Breaks execution when a specified exception is thrown.

onuncaught

Breaks when an uncaught exception occurs; default is n.

launch

Command to run when the debugger stops.

timeout

Timeout in milliseconds. When suspend=y it is the wait‑for‑connection timeout; when suspend=n it is the post‑connection usage timeout.

Common Commands

Examples that illustrate different option combinations:

Socket listening on port 8000, blocking until a debugger connects (default suspend=y):

-agentlib:jdwp=transport=dt_socket,server=y,address=8000

Socket on port 8000, block for 5 seconds then abort if no debugger connects:

-agentlib:jdwp=transport=dt_socket,server=y,address=localhost:8000,timeout=5000

Shared‑memory connection with stdout printing, non‑blocking:

-agentlib:jdwp=transport=dt_shmem,server=y,suspend=n

Socket connection to a remote host, blocking until connection succeeds:

-agentlib:jdwp=transport=dt_socket,address=myhost:8000

Socket on port 8000, block until connection, and break on java.io.IOException to launch a custom stub:

-agentlib:jdwp=transport=dt_socket,server=y,address=8000,onthrow=java.io.IOException,launch=/usr/local/bin/debugstub

How to Enable Remote Debugging in IntelliJ IDEA

First, run the packaged Spring Boot jar on the server with a command such as:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9193 -jar debug-demo.jar

In IDEA, open Edit Configurations, click the + button and choose Remote. Fill in the server’s address and port, then click OK.

After saving the configuration, click the DEBUG button. Because suspend=n was used, the server does not wait for the debugger; you can invoke any endpoint and debug it in real time.

Conclusion

Remote debugging lets you inspect server‑side code without launching the whole application locally, saving time during bug fixing.

For more in‑depth Java interview material (≈10 MB), reply with Java面试宝典 in the public account.