skip to content

How do you diagnose a hung Java application you suspect is deadlocked, using a thread dump?

level: middleimportance: must knowfreq 58%

answer

  1. jstack / jcmd Thread.print / kill -3 (SIGQUIT)
  2. BLOCKED or lock-parked threads; 'Found one ... deadlock'
  3. Match 'waiting to lock <id>' to who 'locked <id>'
  4. Take 2–3 dumps to confirm it's stuck, not transient
  5. ThreadMXBean.findDeadlockedThreads() for programmatic checks

basics

~20 s

Take 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 s

When 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
java
// 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

for a junior

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.

for a middle

Reads the dump: matches 'waiting to lock' object ids to holders, takes multiple dumps, uses the auto-detector.

for a senior

Knows the detector's limits (non-monitor/external locks, virtual threads) and uses ThreadMXBean / pool analysis for those cases.

for a principal

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