Troubleshooting IllegalStateException in Java Project Loom Virtual Threads with Legacy JNI Code

Project Loom’s virtual threads, introduced as a standard feature in Java 21 (and available as a preview feature since JDK 19 via JEP 444), promise a paradigm shift in writing scalable, concurrent Java applications. By providing lightweight, JVM-managed threads, they allow developers to write simple, blocking-style code that can handle millions of concurrent tasks with minimal overhead. However, when these modern virtual threads interact with legacy Java Native Interface (JNI) code, a common and sometimes perplexing issue can arise: the IllegalStateException.

This article provides a comprehensive guide for experienced Java developers on understanding, diagnosing, and troubleshooting IllegalStateExceptions that occur when virtual threads execute or interact with JNI code. We’ll explore the concept of “pinning,” diagnostic tools, and best practices for ensuring smooth interoperability.

The Root Cause: Virtual Thread Pinning with JNI

The primary reason IllegalStateExceptions and other unexpected behaviors emerge with JNI and virtual threads is pinning.

Virtual Threads: Designed to be lightweight, they “park” (unmount from their carrier platform thread) when they encounter a blocking operation (like I/O). This allows the carrier thread (a traditional OS thread, usually from a shared pool like the ForkJoinPool) to execute other virtual threads, achieving high concurrency.
JNI Calls: When a virtual thread executes a native method via JNI, it becomes pinned to its carrier platform thread for the entire duration of the native method call. This means the virtual thread cannot unmount, and its carrier thread is exclusively dedicated to that JNI call. The same pinning behavior occurs if a virtual thread executes code within a synchronized block or method.
Legacy JNI Code: Native code written before Project Loom often assumes it’s running on a standard platform thread. It might perform long-blocking operations, rely on thread-local storage specific to platform threads, or manage thread lifecycles in ways incompatible with virtual thread semantics.

An IllegalStateException typically arises when an operation is attempted on or by a virtual thread while it’s in a state (like pinned and executing a native method) that makes the operation invalid. The Loom runtime or other JVM components might detect this inconsistency and throw the exception.

As stated in JEP 444 (Virtual Threads): “A virtual thread cannot be unmounted from its carrier thread during native method calls or synchronized blocks.” This is a fundamental constraint.

Common Scenarios Leading to `IllegalStateException`

While specific error messages can vary, the underlying theme is often a conflict due to pinning:

Attempting to Park a Pinned Carrier:
- Symptom: An IllegalStateException with messages like “Attempting to park a pinned carrier thread” or related to continuation parking failures.
- Cause: If a virtual thread is pinned by a JNI call, and then (perhaps through a callback from JNI into Java, or due to a Thread.sleep() call that Loom attempts to optimize) an operation tries to park/unmount this virtual thread, the conflict arises. The Loom scheduler expects to manage the virtual thread’s lifecycle, but pinning prevents this.
Incorrect JNI Thread Management:
- Symptom: IllegalStateException or even JVM crashes occurring unpredictably.
- Cause: If JNI code running on a carrier thread for a virtual thread incorrectly calls DetachCurrentThread(). Carrier threads are managed by the Loom scheduler (e.g., ForkJoinPool) and must not be detached by user JNI code. This can corrupt the scheduler’s state.
Unsupported Thread Operations on Virtual Threads:
- Symptom: IllegalStateException directly from a Thread method.
- Cause: Virtual threads do not support all operations applicable to platform threads (e.g., setPriority(int), stop(), suspend(), resume()). If JNI code calls back into Java, and that Java code attempts such an operation on the current (virtual) thread, an exception will be thrown.
Conflicts with JNI Critical Sections:
- Symptom: IllegalStateException: Stackwalking in a JNI critical section or similar.
- Cause: JNI functions like GetPrimitiveArrayCritical or GetStringCritical create a “critical region” where garbage collection is disabled, and the thread is effectively pinned even more stringently. If, during this section, another operation (e.g., from a signal handler, another thread via JNI, or certain JVM internal actions) attempts tasks like stack walking on this thread, it can lead to an IllegalStateException. While a general JNI concern, long-running critical sections on a virtual thread’s carrier are particularly problematic.

Diagnostic Tools and Techniques

Identifying the source of pinning and the context of the IllegalStateException is key.

1. Trace Pinned Threads (`-Djdk.tracePinnedThreads`)

This is the most crucial JVM option for diagnosing pinning issues.

-Djdk.tracePinnedThreads=full: Prints a full stack trace when a virtual thread pins or attempts an operation (like parking) while pinned. This usually points directly to the JNI method or synchronized block causing the pin.
-Djdk.tracePinnedThreads=short: Provides a more concise output.

1
java -Djdk.tracePinnedThreads=full -jar myapplication.jar

The output will show when a thread pins (e.g., JavaThread ... pinned starting ...) and when it unpins. If an operation fails due to pinning, the stack trace will be invaluable.

2. Java Flight Recorder (JFR)

JFR provides rich diagnostic information with low overhead. Key events include:

jdk.VirtualThreadPinned: Records an event when a virtual thread is pinned to its carrier. The event includes the duration of the pinning, which is vital for identifying long-blocking JNI calls.
jdk.VirtualThreadSubmitFailed: Indicates tasks cannot be submitted to the virtual thread scheduler, possibly due to carrier pool exhaustion exacerbated by too many pinned threads.

3. Thread Dumps

Standard thread dumps (using jstack, jcmd <pid> Thread.print, or VisualVM) can still be useful.

Virtual threads will be listed, often showing their carrier thread.
If a virtual thread is pinned executing a JNI method, its stack trace will include the native method frame.
Look for platform threads in the ForkJoinPool (default carrier pool) that are stuck in native code.

4. Verbose Logging (`-Xlog`)

Detailed logging from Loom can provide context:

-Xlog:loom+thread=debug or -Xlog:loom+thread=trace (very verbose). This can show pinning, unpinning, parking, and scheduling decisions.

Best Practices for JNI with Virtual Threads

To prevent or mitigate IllegalStateExceptions and performance degradation:

Keep JNI Calls Short and Non-Blocking: This is the paramount rule. If a native method executes quickly, the pinning duration is minimal and its impact negligible. If the JNI call involves I/O or potentially long computations, it’s problematic for virtual threads designed for non-blocking behavior.

Offload Long-Blocking JNI Calls to Dedicated Platform Threads: If a JNI call is inherently long-blocking and cannot be refactored:

Create a dedicated ExecutorService backed by platform threads.
Submit the task that makes the JNI call to this dedicated executor.
Use CompletableFuture.supplyAsync(this::longBlockingJniCall, dedicatedPlatformExecutor) to execute the JNI call asynchronously and bridge the result back to the calling virtual thread context if needed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Example: Offloading a blocking JNI call
class MyLegacyJniService {
    private final ExecutorService platformThreadExecutor =
        Executors.newFixedThreadPool(Runtime.getRuntime().availableProcessors()); // Or a cached pool

    public native String legacyBlockingGetData(String param); // The JNI method

    public CompletableFuture<String> getDataAsync(String param) {
        return CompletableFuture.supplyAsync(() -> legacyBlockingGetData(param), platformThreadExecutor);
    }

    // Call from virtual thread:
    // getDataAsync(myParam).thenAccept(result -> ...);
}

Favor java.util.concurrent.ReentrantLock over synchronized:
- synchronized blocks/methods cause pinning for their entire duration.
- ReentrantLock also causes pinning if a virtual thread holds the lock while executing a JNI method (or any other operation that would normally park).
- However, ReentrantLock offers more flexibility (e.g., tryLock). If the lock’s scope doesn’t need to include the JNI call itself, ReentrantLock can provide finer-grained control. The key is that if a JNI call occurs while any monitor (implicit via synchronized or explicit via ReentrantLock) is held by the virtual thread, it will be pinned.
Review and Modernize JNI Code (If Possible):
- No DetachCurrentThread on Carrier Threads: Native code must not call DetachCurrentThread if it’s running on a carrier thread that was mounted for a virtual thread.
- Minimize JNI Critical Sections: Use GetPrimitiveArrayCritical and GetStringCritical sparingly and ensure the code within these sections is extremely short, as they disable GC and have stricter pinning implications.
Transition to the Foreign Function & Memory API (FFM API):
- The FFM API (standard in Java 22+, preview in earlier versions like JDK 19, 21 via JEP 454 and its predecessors) is the modern, recommended alternative to JNI.
- It is designed with virtual threads in mind and can often interact with native code without pinning the virtual thread, especially for non-blocking native functions or when managing call transitions carefully.
- For new native integrations, FFM API should be the default choice. For legacy code, migrating from JNI to FFM API can be a long-term solution.

Troubleshooting Steps for `IllegalStateException`

Reproduce Consistently: Try to create a minimal, reproducible test case.
Enable Pinning Traces: Add -Djdk.tracePinnedThreads=full to your JVM arguments. Examine the output for stack traces at the point of pinning or when an operation fails due to pinning. This often directly identifies the problematic JNI call or synchronized block.
Capture and Analyze JFR Recordings: Focus on jdk.VirtualThreadPinned events. Note the duration and frequency of pinning. Long durations are red flags.
Examine Thread Dumps:
- Identify the virtual thread involved (often mentioned in the IllegalStateException message or discernible from application logic).
- Find its carrier platform thread in the dump.
- Inspect the stack trace of the carrier thread. If it’s in a JNI method, that’s the source of pinning.
Review Java Call Sites: Trace back from the JNI call in your Java code. Is it wrapped in synchronized? Is it part of a complex sequence of operations that might conflict with a pinned state (e.g., attempting further blocking operations that Loom can’t handle due to the pin)?
Scrutinize JNI Native Code:
- Is the native method performing I/O, waiting on native locks, or executing a long computation?
- Does it call back into Java? If so, what does that Java callback code do? (e.g., Thread.sleep(), further blocking I/O, synchronized blocks).
- Does it manage threads (AttachCurrentThread, DetachCurrentThread)? Ensure DetachCurrentThread is not called on a carrier thread for a virtual thread.

When Pinning is Unavoidable (and Short)

Sometimes, a JNI call is inherently short and essential. If jdk.tracePinnedThreads shows pinning, but the duration is consistently tiny (microseconds), and no IllegalStateExceptions occur, this might be acceptable. The Loom scheduler can compensate for a small number of pinned threads by potentially adding more carrier threads to the ForkJoinPool (up to a limit). However, relying on this compensation for many or long-pinned threads defeats the purpose of virtual threads.

Conclusion

IllegalStateExceptions when using Project Loom’s virtual threads with legacy JNI code are almost always rooted in the concept of thread pinning. JNI calls inherently pin the virtual thread to its carrier, making the carrier unavailable for other virtual threads and potentially conflicting with Loom’s scheduling and state management mechanisms.

The primary strategy for resolving these issues is to ensure JNI calls made from virtual threads are brief and non-blocking. Long-blocking native operations should be offloaded to dedicated platform threads. For new development, the Foreign Function & Memory API offers a more robust and Loom-aware alternative to JNI. By leveraging JVM diagnostic options like -Djdk.tracePinnedThreads, JFR, and careful code review, developers can effectively troubleshoot these exceptions and successfully integrate legacy native code into modern, scalable Java applications built with virtual threads.