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.

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
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar| Option | Meaning |
|---|---|
transport=dt_socket | Listen on a TCP socket |
server=y | This JVM waits for the debugger to connect |
suspend=y or n | Wait for the debugger before starting, or start immediately |
address=*:5005 | Port 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
jdb -attach localhost:5005> stop at dev.javahacks.OrderService:42
Set breakpoint dev.javahacks.OrderService:42
> threads
> where
> print order.total
> locals
> step
> contThe 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
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:devPublish 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
kubectl port-forward pod/orders-7d9c8-abcde 5005:5005Add 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=*:5005on a public or shared network. - Prefer localhost binding plus an SSH or
kubectltunnel. - 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:
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-hostThe 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:
$ 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
> contstop 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:
| Need | Tool | Effect on the service |
|---|---|---|
| See a value at one line | A logpoint in the IDE, which prints without stopping | Slight slowdown |
| Find where time goes | A Flight Recorder profile | A few percent overhead |
| See the state once | A heap dump or a thread dump | A pause while it is written |
| Step through logic | A breakpoint on a local or staging copy | Stops 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:
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:devInside 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.


