rgoussu.dev
rgoussu@goussu: ~/library/java/jdk-and-tools
❯ ~/library/java/jdk-and-tools cat jdb.md

jdb — the CLI debugger and JDWP

# The JDK's command-line debugger and the JDWP/JDI machinery behind it — the same wire protocol every IDE debugger speaks.

Conceptsaved 2026-08-09 #java#jvm#tooling#debugging

Overview

jdb is the JDK's command-line debugger: breakpoints, stepping, stack and variable inspection over a text prompt. Almost nobody debugs in jdb daily — IDEs are the front-end of choice — but it matters as the reference client of the Java debugging architecture (JPDA): the JDWP wire protocol the JVM exposes, and the JDI client API that jdb, IntelliJ and VS Code all use. Knowing the JDWP flags is what makes remote debugging of a containerised or server JVM work, whatever the front-end.

Key points

  • Architecture (JPDA): JVMTI (in-VM native interface) → JDWP (wire protocol, exposed by -agentlib:jdwp) → JDI (com.sun.jdi, the Java client API). Any JDI client can attach to any JDWP-speaking JVM — IDE vs jdb is purely a front-end choice.
  • The canonical server flag: -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 — target JVM listens on 5005; suspend=y instead blocks the JVM before main until a debugger attaches (essential for debugging startup). address=*:5005 binds all interfaces (Java 9+ defaults to localhost only — deliberate; JDWP is unauthenticated remote code execution, never expose it publicly, tunnel over SSH/port-forward instead).
  • Attach vs listen: attach — the debugger connects to a JVM that is listening (server=y, the common case): jdb -attach host:5005. Listen — the debugger waits (jdb -listen 5005) and the JVM dials out with server=n,address=debughost:5005; useful when the JVM is behind NAT or short-lived.
  • Launch mode: jdb -sourcepath src Main starts the program under the debugger directly.
  • Session commands: stop at com.example.Foo:42 / stop in com.example.Foo.bar, run, step/next/cont, print expr, locals, where (stack), threads, catch java.io.IOException (break on exception).
  • When jdb is actually the right tool: a bare server/container with no IDE reachable, quick scripted checks, or verifying that the JDWP port itself works before blaming the IDE.
  • IDE remote debugging is the same flag: paste the -agentlib:jdwp=... into the JVM, create a "Remote JVM Debug" run config pointing at host:5005 — Kubernetes usage is a kubectl port-forward in front of exactly this.

Examples

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar
jdb -attach localhost:5005
> stop in com.example.OrderService.place
> cont
> where
> print order.total()

Related

  • JDK & tools — parent catalogue of the JDK toolchain.
  • Java launcher — where the -agentlib:jdwp flag lives.
  • jstack — when you only need stacks, not interactive control.
  • jcmd — non-interactive diagnostics for JVMs you cannot restart with JDWP on.
  • AppSec fundamentals — an exposed JDWP port is a textbook remote-execution hole.