Skip to content
javahacks.dev
Debugging

JDB Remote Debugging Setup for Java Apps and Containers

Set up Java remote debugging with the JDWP agent, connect from jdb or an IDE, reach a container or Kubernetes pod safely and avoid exposing the port.

6 min read
Summarize in AI
Flat illustration of a magnifier over lines of a log, with the OpenJDK, Apache Maven, Gradle and JUnit5 logos.

A debugger does not have to run next to the code. The JVM can listen for debugger connections, and you can attach from another machine. This is how you debug a service in a container, a VM or a pod.

Enable the agent

Shell
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar
OptionMeaning
transport=dt_socketListen on a TCP socket
server=yThis JVM waits for the debugger to connect
suspend=y or nWait for the debugger before starting, or start immediately
address=*:5005Port 5005 on all interfaces (JDK 9 and later default to localhost only if you write just 5005)

Use suspend=y to debug start-up code. In Spring Boot you can pass it through Maven: ./mvnw spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005", and with Gradle ./gradlew bootRun --debug-jvm. The application-level view of breakpoints is in debugging Spring Boot.

Connect with jdb

Shell
jdb -attach localhost:5005
Text
> stop at dev.javahacks.OrderService:42
Set breakpoint dev.javahacks.OrderService:42
> threads
> where
> print order.total
> locals
> step
> cont

The common commands: stop at Class:line, stop in Class.method, where (stack of the current thread), locals, print expr, step, next, cont, clear. jdb is spartan, and for anything beyond a quick look an IDE is better. IntelliJ IDEA and Eclipse use "Remote JVM Debug" configurations that connect to the same host and port, and give conditional breakpoints and logpoints, see conditional breakpoints.

Docker

Shell
docker run -p 127.0.0.1:5005:5005 \
  -e JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" \
  myapp:dev

Publish the port on the loopback of the host (127.0.0.1:5005:5005), not on all interfaces. JAVA_TOOL_OPTIONS avoids editing the image command, as described in JVM options in Docker.

Kubernetes

Shell
kubectl port-forward pod/orders-7d9c8-abcde 5005:5005

Add the agent option to the pod through an environment variable in a debug deployment, then forward the port to your laptop. The debugger connects to localhost:5005, and traffic travels through the Kubernetes API tunnel. Remove the variable afterwards. On a shared cluster, use a copy of the workload, not the live deployment.

Security

The JDWP port has no authentication and no encryption. Anyone who can reach it can run arbitrary code in your JVM: set a field, call a method, load a class. Treat it like root access.

  • Never expose address=*:5005 on a public or shared network.
  • Prefer localhost binding plus an SSH or kubectl tunnel.
  • Do not enable it in production images by default. Make it a deliberate, temporary change.
  • Scanners look for open 5005 ports, and open debug ports have led to real compromises.

Behaviour on shared environments

A breakpoint suspends the thread that hits it, and by default all threads of the JVM (the suspend policy). On a server handling traffic, that freezes every request. In the IDE, set breakpoints to suspend only the thread, and prefer logpoints in shared environments. Health checks fail while the JVM is suspended, and Kubernetes may restart the pod, so extend the probe timeouts in a debug copy.

Bind the port safely

Since Java 9 the agent listens on localhost only when the address has no host, so address=5005 is reachable from the same machine and not from the network. The wildcard form address=*:5005 opens the port to every interface, and the debug protocol has no authentication. Anyone who can reach the port can run arbitrary code in the process. For a remote target, keep the agent on localhost and reach it through a tunnel:

Shell
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:5005 -jar app.jar
ssh -L 5005:127.0.0.1:5005 deploy@app-host

The IDE or jdb then connects to localhost:5005 on your machine, and the traffic goes through the encrypted SSH channel. In Kubernetes, kubectl port-forward pod/shop-7d9f 5005:5005 does the same, and no service or ingress needs to expose the port.

A short jdb session

The command line debugger is clumsy compared with an IDE, and it is present on every JDK, which makes it useful on a server with no tools installed. A typical session:

Text
$ jdb -attach localhost:5005
> stop at dev.javahacks.OrderService:42
Set breakpoint dev.javahacks.OrderService:42
> cont
Breakpoint hit: "thread=http-nio-8080-exec-3", dev.javahacks.OrderService.place(), line=42
> print order.total
 order.total = 129.90
> locals
> step
> cont

stop in Class.method sets a breakpoint on a method, where prints the stack, threads lists threads, and clear removes a breakpoint. The cont command resumes the program. Without the line numbers in the class files, jdb cannot show locals, so compile with -g or the default Maven settings that include debug information.

What a breakpoint does to a live service

By default a breakpoint suspends all threads of the virtual machine, not only the one that hit it. On a shared server that stops every other request for as long as you look at the variables, and health checks fail, and a load balancer pulls the instance. IDEs offer a thread-only suspend policy, and with it the other threads continue. For production-like systems, prefer methods that do not stop the process:

NeedToolEffect on the service
See a value at one lineA logpoint in the IDE, which prints without stoppingSlight slowdown
Find where time goesA Flight Recorder profileA few percent overhead
See the state onceA heap dump or a thread dumpA pause while it is written
Step through logicA breakpoint on a local or staging copyStops threads

Debugging a copy of the problem with the same data is nearly always better than stepping through the live one.

Containers and the build

The image has to start the JVM with the agent option. With the JAVA_TOOL_OPTIONS variable you do not have to change the entry point, and it is read by every JVM started in the container:

Shell
docker run -p 127.0.0.1:5005:5005 \
  -e JAVA_TOOL_OPTIONS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" \
  shop:dev

Inside the container the agent must listen on all interfaces for the published port to reach it, and the 127.0.0.1: prefix on the port mapping keeps it closed to the network on the host. Do not bake the option into an image that is deployed beyond development, since a forgotten debug port is an open door.

Leaving no debug port behind

A debug port that stays open after a debugging session is a vulnerability. Make it a routine to remove the option after use: the environment variable, the Kubernetes patch or the Compose override should be reverted in the same session, and the pod restarted. A periodic scan of the cluster for containers that expose port 5005 or have jdwp in their arguments finds the ones that were forgotten.

Add the scan to the platform checks, and the policy becomes enforced by a tool, which is more reliable than a note in a wiki.

Where this does not apply

For production issues, a read-only approach such as logs, metrics, thread dumps and Arthas is safer than a debugger. The reference is the [jdb documentation](https://docs.oracle.com/en/java/javase/25/docs/specs/man/jdb.html), and the JPDA connection guide describes the protocol.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.