{"record":{"id":"e03a8207ebf82a70","repo":"eclipse-vertx/vert.x","slug":"this-java-runtime-does-not-support-virtual-threads","errorCode":null,"errorMessage":"This Java runtime does not support virtual threads","messagePattern":"This Java runtime does not support virtual threads","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/impl/VertxImpl.java","lineNumber":628,"sourceCode":"                                   CloseFuture closeFuture,\n                                   WorkerPool workerPool,\n                                   String deploymentID,\n                                   ClassLoader tccl) {\n    EventExecutor eventExecutor;\n    EventLoopExecutor eventLoopExecutor = new EventLoopExecutor(eventLoop);\n    WorkerPool wp;\n    switch (threadingModel) {\n      case EVENT_LOOP:\n        wp = workerPool != null ? workerPool : this.workerPool;\n        eventExecutor = eventLoopExecutor;\n        break;\n      case WORKER:\n        wp = workerPool != null ? workerPool : this.workerPool;\n        eventExecutor = new WorkerExecutor(wp, new WorkerTaskQueue());\n        break;\n      case VIRTUAL_THREAD:\n        if (!isVirtualThreadAvailable()) {\n          throw new IllegalStateException(\"This Java runtime does not support virtual threads\");\n        }\n        wp = virtualThreadWorkerPool;\n        eventExecutor = new WorkerExecutor(virtualThreadWorkerPool, new WorkerTaskQueue());\n        break;\n      default:\n        throw new UnsupportedOperationException();\n    }\n    return createContext(threadingModel, eventLoopExecutor, eventExecutor, wp, closeFuture, deploymentID, tccl);\n  }\n\n  public ContextImpl createContext(ThreadingModel threadingModel,\n                                   EventLoopExecutor eventLoopExecutor,\n                                   EventExecutor eventExecutor,\n                                   WorkerPool workerPool,\n                                   CloseFuture closeFuture,\n                                   String deploymentID,\n                                   ClassLoader tccl) {\n    return new ContextImpl(this,","sourceCodeStart":610,"sourceCodeEnd":646,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/impl/VertxImpl.java#L610-L646","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Run the application on JDK 21 or later where virtual threads (JEP 444) are final","Check java.version at startup and fail fast with a clear message before deploying virtual-thread verticles","If the runtime cannot be upgraded, use ThreadingModel.EVENT_LOOP or WORKER instead","Verify the actual runtime with java -version; container images may differ from the dev machine JDK"],"exampleFix":"// before\nDeploymentOptions opts = new DeploymentOptions().setThreadingModel(ThreadingModel.VIRTUAL_THREAD);\nvertx.deployVerticle(new MyVerticle(), opts); // throws on JDK 17\n// after\nif (Runtime.version().feature() >= 21) {\n  vertx.deployVerticle(new MyVerticle(), new DeploymentOptions().setThreadingModel(ThreadingModel.VIRTUAL_THREAD));\n} else {\n  vertx.deployVerticle(new MyVerticle()); // default event-loop\n}","handlingStrategy":"validation","validationCode":"if (Runtime.version().feature() < 21) {\n  throw new IllegalStateException(\"Virtual threads require JDK 21+; current: \" + Runtime.version());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin runtime JDK >= 21 in Dockerfiles and CI images","Add a startup capability check before enabling ThreadingModel.VIRTUAL_THREAD","Document the JDK requirement next to virtual-thread deployment options"],"tags":["jvm","virtual-threads","deployment","configuration"],"backgroundTag":"unsupported-platform","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}