{"record":{"id":"8032cef7e8eedc6e","repo":"quarkusio/quarkus","slug":"unable-to-create-route-handler-handlerclassna","errorCode":null,"errorMessage":"Unable to create route handler: \" + handlerClassName","messagePattern":"Unable to create route handler: \" \\+ handlerClassName","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/reactive-routes/runtime/src/main/java/io/quarkus/vertx/web/runtime/VertxWebRecorder.java","lineNumber":50,"sourceCode":"            VertxHttpBuildTimeConfig httpBuildTimeConfig) {\n        this.httpConfig = httpConfig;\n        this.httpBuildTimeConfig = httpBuildTimeConfig;\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    public Handler<RoutingContext> createHandler(String handlerClassName) {\n        try {\n            ClassLoader cl = Thread.currentThread().getContextClassLoader();\n            if (cl == null) {\n                cl = VertxWebRecorder.class.getClassLoader();\n            }\n            Class<? extends Handler<RoutingContext>> handlerClazz = (Class<? extends Handler<RoutingContext>>) cl\n                    .loadClass(handlerClassName);\n            RouteHandler handler = (RouteHandler) handlerClazz.getDeclaredConstructor().newInstance();\n            return handler;\n        } catch (InstantiationException | IllegalAccessException | ClassNotFoundException | NoSuchMethodException\n                | InvocationTargetException e) {\n            throw new IllegalStateException(\"Unable to create route handler: \" + handlerClassName, e);\n        }\n    }\n\n    public Handler<RoutingContext> runOnVirtualThread(Handler<RoutingContext> routeHandler) {\n        return new VirtualThreadsRouteHandler(routeHandler);\n    }\n\n    public Handler<RoutingContext> compressRouteHandler(Handler<RoutingContext> routeHandler, HttpCompression compression) {\n        if (httpBuildTimeConfig.enableCompression()) {\n            return new HttpCompressionHandler(routeHandler, compression,\n                    compression == HttpCompression.UNDEFINED\n                            ? Set.copyOf(httpBuildTimeConfig.compressMediaTypes().orElse(List.of()))\n                            : Set.of());\n        } else {\n            return routeHandler;\n        }\n    }\n","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/reactive-routes/runtime/src/main/java/io/quarkus/vertx/web/runtime/VertxWebRecorder.java#L32-L68","documentation":"VertxWebRecorder.createHandler loads a handler class generated at build time and instantiates it reflectively at startup. If the class cannot be loaded or instantiated (missing, wrong name, or no no-arg constructor), an IllegalStateException wrapping the reflective cause is thrown.","triggerScenarios":"Calling VertxWebRecorder.createHandler with a handlerClassName that was not generated by ReactiveRoutesProcessor, refers to a class removed/renamed between builds, or has no public no-arg constructor.","commonSituations":"Stale build artifacts after refactoring generated handler names; mixing versions of quarkus-vertx-http and quarkus-reactive-routes; custom code calling the recorder directly with a mistyped class name; native-image builds where the class was not registered for reflection.","solutions":["Run a clean rebuild (./mvnw clean install) so generated handler classes match the current code.","Verify the handlerClassName corresponds to a class generated by ReactiveRoutesProcessor and the extension versions are aligned.","For native builds, ensure the generated handler class is registered for reflection (Quarkus normally does this automatically; check for custom exclude patterns in native configuration)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// validate the class exists and is instantiable before use\nClass<?> c = Class.forName(handlerClassName);\nif (!Handler.class.isAssignableFrom(c) || c.getDeclaredConstructors()[0].getParameterCount() != 0)\n    throw new IllegalStateException(\"Invalid handler class: \" + handlerClassName);","typeGuard":null,"tryCatchPattern":"try {\n    return recorder.createHandler(name);\n} catch (IllegalStateException e) {\n    log.error(\"Handler {} missing; rebuilding? cause={}\", name, e.getCause());\n    throw e;\n}","preventionTips":["Run clean builds after refactoring generated handler names","Keep quarkus-reactive-routes and quarkus-vertx-http versions aligned","Verify reflection registration for native image builds","Never hardcode generated handler class names"],"tags":["quarkus","reactive-routes","reflection","classloading"],"backgroundTag":"class-not-found","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}