eclipse-vertx/vert.x · error · IllegalStateException

This Java runtime does not support virtual threads

Error message

This Java runtime does not support virtual threads

What it means

Vert.x throws this IllegalStateException when you request a ThreadingModel.VIRTUAL_THREAD context or deployment on a JVM that lacks virtual thread support (Java < 21 or Loom previews unavailable). Virtual thread contexts need java.lang.Thread.Builder.OfVirtual, which only exists on modern JDKs. The check happens when creating the context in VertxImpl, before any task runs.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/VertxImpl.java:628

                                   CloseFuture closeFuture,
                                   WorkerPool workerPool,
                                   String deploymentID,
                                   ClassLoader tccl) {
    EventExecutor eventExecutor;
    EventLoopExecutor eventLoopExecutor = new EventLoopExecutor(eventLoop);
    WorkerPool wp;
    switch (threadingModel) {
      case EVENT_LOOP:
        wp = workerPool != null ? workerPool : this.workerPool;
        eventExecutor = eventLoopExecutor;
        break;
      case WORKER:
        wp = workerPool != null ? workerPool : this.workerPool;
        eventExecutor = new WorkerExecutor(wp, new WorkerTaskQueue());
        break;
      case VIRTUAL_THREAD:
        if (!isVirtualThreadAvailable()) {
          throw new IllegalStateException("This Java runtime does not support virtual threads");
        }
        wp = virtualThreadWorkerPool;
        eventExecutor = new WorkerExecutor(virtualThreadWorkerPool, new WorkerTaskQueue());
        break;
      default:
        throw new UnsupportedOperationException();
    }
    return createContext(threadingModel, eventLoopExecutor, eventExecutor, wp, closeFuture, deploymentID, tccl);
  }

  public ContextImpl createContext(ThreadingModel threadingModel,
                                   EventLoopExecutor eventLoopExecutor,
                                   EventExecutor eventExecutor,
                                   WorkerPool workerPool,
                                   CloseFuture closeFuture,
                                   String deploymentID,
                                   ClassLoader tccl) {
    return new ContextImpl(this,

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Run the application on JDK 21 or later where virtual threads (JEP 444) are final
2. Check java.version at startup and fail fast with a clear message before deploying virtual-thread verticles
3. If the runtime cannot be upgraded, use ThreadingModel.EVENT_LOOP or WORKER instead
4. Verify the actual runtime with java -version; container images may differ from the dev machine JDK

Example fix

// before
DeploymentOptions opts = new DeploymentOptions().setThreadingModel(ThreadingModel.VIRTUAL_THREAD);
vertx.deployVerticle(new MyVerticle(), opts); // throws on JDK 17
// after
if (Runtime.version().feature() >= 21) {
  vertx.deployVerticle(new MyVerticle(), new DeploymentOptions().setThreadingModel(ThreadingModel.VIRTUAL_THREAD));
} else {
  vertx.deployVerticle(new MyVerticle()); // default event-loop
}

if (Runtime.version().feature() < 21) {
  throw new IllegalStateException("Virtual threads require JDK 21+; current: " + Runtime.version());
}

When it happens

Trigger: Calling deployVerticle with DeploymentOptions.setThreadingModel(ThreadingModel.VIRTUAL_THREAD), or Vertx.getOrCreateContext()/context creation with VIRTUAL_THREAD, on a runtime where isVirtualThreadAvailable() returns false (JDK 17 or earlier, or a JVM with virtual threads disabled).

Common situations: Running an app built for JDK 21 on a JDK 8/11/17 runtime; Docker base images pinned to an older JRE; build toolchain targeting 21 but CI executing with an older JDK; embedded devices with old JVMs.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• Can't specify < 1 instances to deploy
• workerPoolSize must be > 0
• blockedThreadCheckInterval must be > 0
• maxEventLoopExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/e03a8207ebf82a70. Report an issue: GitHub.