How do you diagnose a hung Java application you suspect is deadlocked, using a thread dump?
answer
- jstack / jcmd Thread.print / kill -3 (SIGQUIT)
- BLOCKED or lock-parked threads; 'Found one ... deadlock'
- Match 'waiting to lock <id>' to who 'locked <id>'
- Take 2–3 dumps to confirm it's stuck, not transient
- ThreadMXBean.findDeadlockedThreads() for programmatic checks
basics
~20 sTake a thread dump (jstack <pid>, jcmd, or kill -3) and look for BLOCKED threads, or WAITING ones parked on a ReentrantLock. The JVM usually prints a 'Found one Java-level deadlock' section naming the threads and the locks they each hold and wait for.
solid answer
~50 sWhen the app hangs, capture a thread dump with jstack <pid>, jcmd <pid> Thread.print, kill -3 <pid> (sends SIGQUIT, dump goes to stdout), or via JMX/VisualVM/JConsole. The JVM's built-in deadlock detector scans the lock graph and, if it finds a cycle, prints a clear 'Found one Java-level deadlock:' block listing each involved thread, the lock it's waiting to lock, and which thread holds it — plus the stack traces. Even without that block, you read it manually: look for BLOCKED threads, note the monitor each is 'waiting to lock' and the ones it holds ('locked'), and trace whether those form a cycle. ReentrantLock waiters are WAITING instead, and only jstack -l lists the locks they hold. Tools like VisualVM, JMC, or ThreadMXBean.findDeadlockedThreads() automate this. Note the built-in detector finds monitor and ReentrantLock cycles but not deadlocks via Semaphores, CountDownLatch, external resources like DB locks, or (since JDK 21) virtual threads — those you must reason about from the stacks.
code
java · 14 lines// Programmatic watchdog: detect deadlocks at runtime
import java.lang.management.*;
ThreadMXBean tmx = ManagementFactory.getThreadMXBean();
long[] ids = tmx.findDeadlockedThreads(); // monitors + ownable synchronizers
if (ids != null) {
ThreadInfo[] infos = tmx.getThreadInfo(ids, true, true);
for (ThreadInfo ti : infos) {
System.out.println(ti.getThreadName()
+ " waiting on " + ti.getLockName()
+ " held by " + ti.getLockOwnerName());
}
}
// CLI equivalents: jcmd <pid> Thread.print | jstack <pid> | kill -3 <pid>go deeper
Knows how to take a thread dump (jstack/jcmd) and that BLOCKED threads, or WAITING ones parked on a lock, and a 'deadlock' section indicate the problem.
Reads the dump: matches 'waiting to lock' object ids to holders, takes multiple dumps, uses the auto-detector.
Knows the detector's limits (non-monitor/external locks, virtual threads) and uses ThreadMXBean / pool analysis for those cases.
Builds production observability: watchdog using findDeadlockedThreads, alerting, and runbooks; reasons about pool-exhaustion and distributed deadlocks the JVM can't see.
## When to suspect deadlock The app **hangs**: requests stop completing, CPU may be near-idle (blocked threads don't burn CPU), but the process is alive. That idle-but-stuck profile is the tell — a busy loop would peg a core; a deadlock parks threads. ## Capturing a thread dump A **thread dump** is a snapshot of the JVM's threads and their stacks at one instant (the traditional dump covers platform threads and, at JDK 27, the virtual threads mounted at that moment; the rest are below). Ways to get one: - `jstack <pid>` — prints the platform threads' stacks to stdout (JDK tool). - `jcmd <pid> Thread.print` — the same dump through `jcmd`; the `jstack` man page calls `jstack` "experimental and unsupported". - `kill -3 <pid>` (Unix) / Ctrl-Break (Windows console) — sends **SIGQUIT**; the JVM dumps to its **stdout** (often the app log), not to the terminal you ran kill from. - GUI: **VisualVM**, **JConsole**, **JDK Mission Control** — all can dump and even highlight deadlocks. Capture **two or three** dumps a few seconds apart: if the same threads are stuck at the same lines every time, it's a real block, not a momentary wait. ## Reading the dump Each thread entry shows a **state** and a stack. Relevant states: - `BLOCKED` — waiting to acquire a monitor someone else holds (the deadlock signature). - `WAITING`/`TIMED_WAITING` — in `wait()`, `park()`, `sleep()`, `join()` — usually *not* a monitor deadlock. A `ReentrantLock` deadlock shows up here, though: each thread is `WAITING`, `parking to wait for` the lock's synchronizer, and the locks it holds are listed only with `jstack -l` (or `jcmd <pid> Thread.print -l`), under `Locked ownable synchronizers`. Within a stack you'll see lines like: ``` - waiting to lock <0x...> (a com.x.Account) // wants this monitor - locked <0x...> (a com.x.Account) // already holds this one ``` Match the **object id** a thread is 'waiting to lock' to the thread that has it 'locked'. If thread T1 waits for a monitor T2 holds, and T2 waits for one T1 holds, that's the cycle. ## The JVM's automatic detector The HotSpot JVM scans for **monitor and `java.util.concurrent` Lock** cycles when you take a dump and, if it finds one, appends an explicit section: ``` Found one Java-level deadlock: ============================= "Thread-A": waiting to lock monitor ... which is held by "Thread-B" "Thread-B": waiting to lock monitor ... which is held by "Thread-A" ``` This names the threads, the locks, and the holders directly — usually all you need. ## Virtual threads (JDK 21 and later) JEP 444 did not extend the traditional dump to virtual threads; at JDK 27 `jcmd Thread.print` prints platform threads and only the virtual threads *mounted* at that moment, HotSpot's deadlock search skips virtual threads and their carriers, and `ThreadMXBean.findDeadlockedThreads()` states that cycles including virtual threads are not found. For a hang among virtual threads: - run `jcmd <pid> Thread.dump_to_file -format=json <file>` (or the default plain format), which lists virtual threads too; - since JDK 25 it carries lock lines (`waiting to lock`, `locked`, `parking to wait for`) but no deadlock section, so you match them into a cycle yourself; - for `java.util.concurrent` locks, JDK 26 and later also print the blocker's owner (`owner #<id>`); JDK 25 prints the blocker without it. ## Programmatic detection `ThreadMXBean` (via `ManagementFactory.getThreadMXBean()`) exposes `findDeadlockedThreads()` (monitors + ownable synchronizers) and `findMonitorDeadlockedThreads()`. You can poll it from a watchdog and log/alert on deadlock in production; it sees platform threads only. ## What the detector misses The built-in detector only knows about intrinsic monitors and AbstractOwnableSynchronizer-based locks (ReentrantLock, ReentrantReadWriteLock). It does **not** detect deadlocks formed via `Semaphore` permits, `CountDownLatch`/`CyclicBarrier`, `wait/notify` mis-coordination, thread-pool exhaustion (e.g. a pool task waiting on another task in the same bounded pool), **external** locks (database row locks, distributed locks), or cycles that include **virtual threads**. For those you read the stacks and reason about the wait graph yourself, or use DB-side tools. ## Putting it together 1. Confirm a hang (idle CPU, requests not completing). 2. Take 2–3 dumps via `jcmd Thread.print`. 3. Look for the 'Found one Java-level deadlock' block; if present, read the named threads/locks. 4. If absent but you still suspect it, find BLOCKED threads and trace 'waiting to lock' vs 'locked' object ids into a cycle (for threads WAITING on a lock, dump with `-l` and match 'parking to wait for' against 'Locked ownable synchronizers'), or consider a non-monitor/external cause.
- Why might the JVM's automatic deadlock section be empty even though the app is clearly hung on a deadlock?The built-in detector only finds cycles over intrinsic monitors and AbstractOwnableSynchronizer locks (ReentrantLock). Deadlocks via Semaphore permits, latches/barriers, thread-pool exhaustion, wait/notify, external DB/distributed locks, or virtual threads (JDK 21+) aren't reported — you trace those from the stacks, jcmd Thread.dump_to_file, or DB tooling.
- Why capture multiple thread dumps a few seconds apart?A single dump can catch a thread in a momentary, legitimate wait. If several dumps show the same threads blocked at the same lines on the same locks, it confirms a true, persistent deadlock rather than transient contention.
- Expecting kill -3 output in the terminal — it goes to the JVM's stdout/log
- Assuming the auto-detector catches Semaphore/latch/DB/pool deadlocks (it doesn't)
- Ruling out deadlock because no thread is BLOCKED (a ReentrantLock deadlock shows WAITING, parked threads)
- Taking a single dump and over-concluding from one snapshot
- Expecting jstack or ThreadMXBean to report a deadlock that involves virtual threads
- ThreadMXBean.findDeadlockedThreads
- Java 1.6
- virtual threads
- Java 21
Assumes JDK 27. The traditional dump's deadlock search skips virtual threads (final in 21), and Thread.print shows only those mounted at that moment; jcmd Thread.dump_to_file lists them too, with lock lines but no deadlock section. JDK 25 prints a parked thread's blocker without its owner; 26 and later add the owner.
context
- The jcmd Commanddocs.oracle.com
- ThreadMXBean (Java SE 27 & JDK 27)docs.oracle.com
- JEP 444: Virtual Threadsopenjdk.org