Master Remote Debugging of Spring Boot with IntelliJ IDEA: A Step‑by‑Step Guide

Sometimes we need remote debugging; this article explores how to perform remote debugging and details of using IDEA for remote debugging.

Configuration

Remote debugging service example with a Spring Boot microservice.

First, start Spring Boot with specific parameters.

IDEA Settings

IDEA version may differ; using 2020.1.1 as an example.

Select Edit Configuration Click the plus sign and choose Remote Configure as shown in the images

Note: ensure the port is not occupied; the port is used for communication with the remote Java process.

Different JDK versions require different JVM arguments:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=50055

For JDK 5‑8:

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=50055

For JDK 9 and above (requires asterisk before port):

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:50055

Startup Script Modification

Use the obtained command line arguments for the remote JVM:

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=50055

Modified startup script:

nohup java \
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=50055 \
-jar remote-debug-0.0.1-SNAPSHOT.jar &

On Windows use ^ for line continuation:

java ^
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=50055 ^
-jar remote-debug-0.0.1-SNAPSHOT.jar

Explanation:

Port can be any free port but must match IDEA remote configuration.

Replace remote-debug-0.0.1-SNAPSHOT.jar with your own jar name.

Remove nohup and & if background execution is not required.

Start Spring Boot, then start the remote configuration in IDEA (image).

Details

Detail 1: Does the program continue after stopping at a local breakpoint?

If the remote debug stops at a breakpoint and you stop the IDEA project, the remote JVM continues executing the remaining logic.

Detail 2: What if the jar code differs from local code?

The code in IDEA must match the remote jar; otherwise line numbers will not align, making debugging confusing.

Detail 3: Where are logs printed?

System.out

and log.info output appear on the remote side, not in the IDEA console.

@GetMapping("/test1")
public String test1() {
    System.out.println("first line");
    System.out.println("second line");
    log.info("log first line");
    log.info("log second line");
    return "ok";
}

Detail 4: Will other users be blocked when a breakpoint is hit?

When a breakpoint pauses execution, the corresponding request is blocked for other users.

Detail 5: Can fixing a bug locally affect the remote running jar?

No; the remote jar must be rebuilt and redeployed; local changes do not affect the already running remote process.

Detail 6 & 7: Drop‑frame issues

Dropping a frame can cause code to be re‑executed, leading to duplicate database inserts or remote calls unless the method is transactional.

Summary

Remote debugging is useful for temporary troubleshooting but has limitations for long‑term use.

Ensuring local and remote code consistency is difficult.

Bugs found via remote debugging require redeployment to fix.