Detecting Deadlock in Java — jstack, ThreadMXBean, and Dump Analysis

Deadlock detection has two flavors: manual thread dump analysis and programmatic via ThreadMXBean.

Symptoms

• Hung requests, frozen app
• CPU near 0% (threads parked, not spinning)
• Heap doesn't grow
• Specific endpoints stop responding

Capturing a thread dump

• jstack — simplest, prints to stdout
• jstack -l — includes lock info
• jcmd Thread.print -l — modern replacement
• kill -3 (SIGQUIT) — JVM prints dump to its stdout
• Take two dumps 5-10s apart to confirm threads are actually stuck

Reading the dump

• Look at bottom of output: "Found one Java-level deadlock" section
• JVM auto-detects monitor (synchronized) deadlocks and spells out the cycle
• Each thread shows: held monitor + waiting monitor + stack trace
• Line numbers tell you exactly where the bug is

Thread states that matter

• `BLOCKED` = waiting for monitor; see - waiting to lock
• `WAITING (parking)` = parked via LockSupport.park, typically ReentrantLock; see - parking to wait for
• `WAITING (on object monitor)` = Object.wait() — waiting for notify
• `RUNNABLE` threads stuck here = tight loop, not deadlock

The ReentrantLock gap

• JVM auto-detector only covers `synchronized`
• ReentrantLock, ReadWriteLock, Semaphore deadlocks do NOT appear in the "Found deadlock" section
• Must manually trace: threads parked → which lock instance → who holds it → is there a cycle?

Programmatic detection — the production answer

• ManagementFactory.getThreadMXBean().findDeadlockedThreads()
• Covers all lock types (monitor and Lock)
• Returns thread IDs; use getThreadInfo(ids, true, true) for full info
• Schedule every 30–60 seconds; alert on-call when it fires
• This is how real monitoring works at scale

Java 21 virtual threads

• Millions of threads makes a text dump huge
• Use jcmd Thread.dump_to_file -format=json for structured output
• Query with jq
• jstack still works but only sees mounted + platform threads
• ThreadMXBean.findDeadlockedThreads() still works

Best practices

• Always take two dumps 5-10s apart — confirms genuinely stuck
• In production, run findDeadlockedThreads periodically as part of health checks
• Alert immediately on detection — deadlocks rarely self-heal
• Annotate dumps with timestamp and which threads form the cycle before escalation

Watch out for

• Container permissions: ptrace/jstack may be blocked in Kubernetes; ensure jcmd paths work
• Heap dumps ≠ thread dumps — don't confuse the two
• `jstack -F` for force attach when JVM is unresponsive — last resort

Recommendation: Bake automated deadlock detection via ThreadMXBean.findDeadlockedThreads() into every production service — run it on a 30–60 second schedule as part of health checks, and alert on-call the moment it fires. For on-demand debugging, use `jcmd Thread.print -l` (modern) or jstack -l (classic); always take two dumps 5-10 seconds apart to confirm threads are actually stuck versus making slow progress. Look for the "Found one Java-level deadlock" section for monitor deadlocks — the JVM hands you the cycle on a plate. For ReentrantLock deadlocks there's no auto-report, so know how to read the parked stack traces. On Java 21, use jcmd Thread.dump_to_file -format=json for dumps that include virtual threads. And don't confuse deadlock (0% CPU) with a tight loop (100% CPU) or slow downstream (some CPU, waiting on external) — each has a different fingerprint in a dump.