On a JDK 25 service running virtual threads, why take jcmd Thread.dump_to_file -format=json rather than Thread.print, and how does a pinned carrier show up?
answer
- unmounted virtual threads have no platform thread
- thread containers instead of a thread list
- carrier field only while mounted
- WAITING plus a carrier
basics
~20 sThread.print shows a virtual thread only while it is mounted on a carrier, so parked ones are missing. Thread.dump_to_file lists all of them by container; in its JSON, a WAITING virtual thread that still has a carrier is pinned.
solid answer
~50 sOn JDK 25, `jcmd <pid> Thread.print` walks platform threads: a carrier prints `Carrying virtual thread #N` and, after its own frames, `Mounted virtual thread #N` with that virtual thread's stack, but every virtual thread that is unmounted, parked on a lock or waiting for I/O, does not appear at all. `jcmd <pid> Thread.dump_to_file -format=json /tmp/threads.json` walks thread containers instead (the root, each thread-per-task executor, each structured scope) and writes every thread with `tid`, `name`, `state`, `"virtual": true`, `stack`, any `parkBlocker` and its `owner`, and `carrier` only while it is mounted. An unmounted waiter has no `carrier`. A virtual thread in `WAITING` or `TIMED_WAITING` that still has one parked without unmounting: it is pinned and is holding that carrier, and when it parked through `LockSupport.park` its stack shows `VirtualThread.parkOnCarrierThread`. Confirm the reason with the `jdk.VirtualThreadPinned` JFR event's `pinnedReason`.
code
bash · 1 linejcmd <pid> Thread.dump_to_file -format=json -overwrite /tmp/threads.jsongo deeper
Recall that virtual threads borrow carrier threads, and that the classic thread print cannot see one that is not mounted.
Explain the container tree in Thread.dump_to_file and the carrier field, and how WAITING plus a carrier means pinned.
Show the counting: pinned virtual threads per carrier, RUNNABLE virtual threads waiting for a carrier, then JFR pinning events to confirm.
Weigh standardising the JSON dump in runbooks and tooling, since classic dump analysis habits silently miss most of a virtual-thread service.
## Why the classic thread print undercounts A **virtual thread** is a Java thread that runs by being **mounted** on a platform **carrier** thread and is **unmounted** whenever it blocks in a way the JDK can suspend. While unmounted it has no operating-system thread at all, only a saved stack on the heap. The classic `jcmd <pid> Thread.print` is a walk over the JVM's platform threads at a safepoint. On JDK 25 it does show what is mounted: a carrier's header is followed by `Carrying virtual thread #N` in place of its state line and, after the carrier's own frames, `Mounted virtual thread #N` and that virtual thread's stack. But a service with 20,000 virtual threads and 8 carriers shows at most 8 of them. The 19,992 that are parked on a lock, waiting on a socket or sleeping are simply not in the output. HotSpot's deadlock finder, which runs after the print, also skips virtual threads and carriers by design. ## What Thread.dump_to_file writes `jcmd <pid> Thread.dump_to_file` walks the JDK's **thread containers** instead of the platform thread list, so every virtual thread is reached. It takes a mandatory file path, `-format=plain` (the default) or `-format=json`, and `-overwrite`, without which it refuses to replace an existing file. The file is written by the target JVM, so the path is resolved in the target's file system. The JSON format is the one to analyse with a script. Its top object is `threadDump` with `processId`, `time`, `runtimeVersion` and a `threadContainers` array. Each container carries `container`, `parent`, `owner`, `threads` and `threadCount`; the root container is named `<root>`, and an executor created by `Executors.newVirtualThreadPerTaskExecutor()` or a structured-concurrency scope gets its own entry. Each thread entry has: | Field | Present when | What it tells you | |---|---|---| | `tid`, `name`, `state` | always | identity and `Thread.State` | | `virtual` | the thread is virtual | written as `true`; absent on platform threads | | `parkBlocker` | the thread is parked | `object`, plus `owner` when the blocker is an owned lock | | `blockedOn` / `waitingOn` | BLOCKED on a monitor / in `Object.wait` | the monitor's identity string | | `stack`, `monitorsOwned` | stack always; monitors if any are held | frames and the monitors held at each depth | | `carrier` | a virtual thread that is mounted | the carrier's thread id | One caution: each thread is captured separately and carries its own `time`, so the JSON is not one atomic snapshot the way the safepoint-based classic print is. ## Reading a pinned carrier When a mounted virtual thread blocks, the JDK normally unmounts it and frees the carrier. When it cannot, the virtual thread is **pinned**: it parks on the carrier, and the carrier is blocked with it. In the JSON that is unmistakable: - a virtual thread whose `state` is `WAITING` or `TIMED_WAITING`, yet which still has a `carrier`; - when it parked through `LockSupport.park`, its top frames run through `java.lang.VirtualThread.parkOnCarrierThread`; - an unmounted waiter in the same state has no `carrier` field at all. On JDK 25 under the default locking mode, holding a `synchronized` monitor no longer pins (the change came in JDK 24). What still pins includes a native or VM frame on the stack, a class initializer on the stack, and waiting for another thread to finish initializing a class. Which construct caused it is the pinning topic's subject; the dump only proves that it happened and on which carrier. ## When every carrier is pinned The default scheduler targets a parallelism equal to what `Runtime.availableProcessors()` reports, unless `jdk.virtualThreadScheduler.parallelism` says otherwise; it can add carriers only up to `jdk.virtualThreadScheduler.maxPoolSize`. If every carrier holds a pinned virtual thread, nothing else can run: 1. Count the virtual threads that have a `carrier` and a waiting `state`, and compare with the carrier count. 2. Count the virtual threads that are RUNNABLE with no `carrier`: they are ready to run and waiting for a free carrier. 3. Read the pinned threads' stacks for the common frame that pins them. 4. Confirm with JFR: `jdk.VirtualThreadPinned` is enabled in the default settings with a 20 ms threshold and records `blockingOperation`, `pinnedReason` and `carrierThread`. A dump in which a few carriers are pinned and most virtual threads are unmounted waiters on one `parkBlocker` is a different story, an ordinary lock or pool wait, and the owner in `parkBlocker` points to it.
- Why does a JSON dump of a virtual-thread service sometimes show thousands of virtual threads parked on the same object with no carrier?That is an ordinary wait, not pinning: they unmounted correctly and are queued on one lock, condition or pool. Read `parkBlocker.object` to see what they wait on and `parkBlocker.owner`, when present, to see which thread holds it, then read that thread's stack.
- Why not just pipe Thread.dump_to_file to the terminal instead of writing a file?Given `-` as the path, the JDK returns the dump to jcmd but caps that reply at 16,000 bytes, which a service with thousands of virtual threads overflows at once. Write to a file the target JVM can create, then copy it out.
- jcmd Thread.print lists every virtual thread, so the JSON dump adds nothing.
- A virtual thread with a carrier field is always running on CPU.
- A WAITING virtual thread without a carrier is pinned to it.
- On JDK 25 every synchronized block pins the virtual thread to its carrier.
- The deadlock finder at the end of Thread.print covers virtual threads too.
Assumes JDK 25: the JSON thread dump's fields and the classic print's mounted-virtual-thread lines are read from the JDK 25 source, and synchronized stopped pinning in JDK 24 under the default locking mode.