How Spring Debugger Enables Agent‑Free Remote Debugging of Java Apps

In September 2025 JetBrains released the Spring Debugger plugin, quickly reaching 300,000 downloads. A recurring community request was the ability to debug remote applications without relying on Java agents.

Why No Debug Agents?

In the Java ecosystem, an agent is a piece of code attached to the JVM, either at startup or runtime, to enhance or monitor the application (e.g., APM tools, bytecode‑enhancement frameworks). A typical launch command looks like:

java -javaagent:/path/to/agent.jar -jar your-app.jar

Agents can inject code before and after method execution, intercept calls, or read memory data, which is powerful but introduces several drawbacks:

Complex startup configuration – additional JVM parameters and a path to the agent JAR are required.

High maintenance cost – the agent version must match the application and JVM version, otherwise startup may fail.

Potential interference – agents modify bytecode and may contain bugs that affect the debugging process.

For local debugging this is manageable, but remote debugging becomes problematic because the application has already started and the opportunity to “plant” an agent has passed.

Answer Lies in the Container Thread Model

Tomcat’s Approach

Tomcat creates a worker thread pool when the server starts. These threads are always ready, similar to waiters in a restaurant waiting for customers (HTTP requests). Spring Debugger can immediately grab an idle worker thread after the application starts and read the ApplicationContext from that thread, without waiting for an HTTP request.

Jetty and Undertow Differ

Both Jetty and Undertow separate I/O threads (the “door greeters”) from worker threads (the “kitchen chefs”). Worker threads are created only when a request arrives. Consequently, the Spring context becomes accessible only after the first HTTP request triggers a worker thread.

Thus, Tomcat’s always‑resident thread pool gives an advantage for remote debugging, despite the extra memory usage.

What Can Spring Debugger Actually Do?

Access Any Production Bean

Instead of modifying code, restarting, or adding temporary logging, you can evaluate expressions directly in the debugger. For example, to clear and view data in categoryRepository:

categoryRepository.deleteAll() // temporary clear
categoryRepository.findAll()   // view data

This provides instant, full‑container access without a restart.

Other Interesting Capabilities

Execute SQL with context parameters :

entityManager.createQuery("SELECT c FROM Category c").getResultList()

Read configuration properties :

environment.getProperty("spring.datasource.url")

Publish events manually :

applicationEventPublisher.publishEvent(new CustomEvent("test"))

Transaction debugging – while paused inside a transaction you can inspect isolation level, propagation status, cache contents, and entity state (e.g., MANAGED, DETACHED) by expanding the transaction node in the Debug window.

Additional UI features include a "Show runtime info" option on beans to view injection relationships, and the ability to see actual runtime values of properties defined in .properties files, even when overridden by environment variables.

How to Configure Remote Debugging

The setup mirrors standard JVM remote debugging (JDWP). In a Docker‑Compose file you add the JDWP options to JAVA_TOOL_OPTIONS:

http-server:
  depends_on:
    - postgresql
  image: 'jb/http-server:latest'
  environment:
    - SPRING_DATASOURCE_URL=jdbc:postgresql://postgresql:5432/db
    - SPRING_DATASOURCE_USERNAME=user
    - SPRING_DATASOURCE_PASSWORD=secret
    - JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
  ports:
    - '8080:8080'
    - '5005:5005'

The crucial line is the JDWP option:

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

Explanation of the flags: server=y: the JVM acts as a debug server waiting for a client. suspend=n: the JVM starts immediately; set to y to wait for a debugger. address=*:5005: listen on port 5005 on all network interfaces.

In IntelliJ IDEA create a Remote JVM Debug configuration, specify the target IP and port, and **must** set the module classpath so the IDE can locate source files; otherwise Spring Debugger’s advanced features are unavailable.

After connecting, Tomcat containers provide the Spring context instantly, while Jetty/Undertow require the first HTTP request to trigger a worker thread.

Limitations

Only embedded containers are supported – Tomcat, Jetty, Undertow. Stand‑alone servlet containers (WAR deployed to an external Tomcat) are not supported.

The remote debug configuration must specify the module classpath; otherwise source lookup fails.

Database structure view is unavailable – you can see the connection but not the table schema.

Conclusion

Zero‑configuration cost – only a standard JDWP port is needed.

No maintenance burden – no agents to version or keep compatible.

Non‑intrusive debugging – the application’s runtime behavior remains unchanged.

With Spring Debugger’s remote debugging, developers can inspect beans, view configuration, run SQL, and analyze transactions on live servers without adding agents or modifying the application.