{"record":{"id":"1a96f799f6d5679f","repo":"quarkusio/quarkus","slug":"unable-to-load-type-name","errorCode":null,"errorMessage":"Unable to load type: ${name}","messagePattern":"Unable to load type: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/vertx/deployment/src/main/java/io/quarkus/vertx/deployment/VertxProcessor.java","lineNumber":287,"sourceCode":"    @BuildStep\n    NativeImageConfigBuildItem reinitializeClassesForNetty() {\n        NativeImageConfigBuildItem.Builder builder = NativeImageConfigBuildItem.builder();\n\n        builder.addRuntimeInitializedClass(\"io.vertx.core.http.impl.http1.Http1ServerResponse\")\n                .addRuntimeInitializedClass(\"io.vertx.core.parsetools.impl.RecordParserImpl\");\n\n        if (QuarkusClassLoader.isClassPresentAtRuntime(\"io.vertx.ext.web.client.impl.MultipartFormUpload\")) {\n            builder.addRuntimeInitializedClass(\"io.vertx.ext.web.client.impl.MultipartFormUpload\");\n        }\n\n        return builder.build();\n    }\n\n    private Class<?> tryLoad(String name, ClassLoader tccl) {\n        try {\n            return tccl.loadClass(name);\n        } catch (ClassNotFoundException e) {\n            throw new IllegalStateException(\"Unable to load type: \" + name, e);\n        }\n    }\n\n    @BuildStep\n    void registerNativeImageResources(BuildProducer<NativeImageResourceBuildItem> resources,\n            BuildProducer<ServiceProviderBuildItem> serviceProviders) {\n        // Accessed by io.vertx.core.impl.VertxBuilder.<init> via ServiceLoader\n        serviceProviders.produce(ServiceProviderBuildItem.allProvidersFromClassPath(VertxServiceProvider.class.getName()));\n        // Accessed by io.vertx.core.impl.VertxImpl.<init>\n        resources.produce(new NativeImageResourceBuildItem(\"META-INF/services/io.vertx.core.spi.VerticleFactory\"));\n    }\n\n}\n","sourceCodeStart":269,"sourceCodeEnd":301,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/vertx/deployment/src/main/java/io/quarkus/vertx/deployment/VertxProcessor.java#L269-L301","documentation":"VertxProcessor.tryLoad loads a class by name from the current thread context classloader during deployment. If the class is missing, the build fails with IllegalStateException wrapping the ClassNotFoundException, meaning a configured/expected Vert.x-related type is not on the application's classpath.","triggerScenarios":"A class name referenced by the extension's build steps (e.g. a codec, verticle, or service type registered via config or SPI) cannot be resolved by the TCCL because the dependency providing it is absent from the deployment classpath.","commonSituations":"Missing Vert.x module dependency in pom.xml/build.gradle; typos in class-name configuration properties; a version change where a class moved packages; removing a dependency that an extension still references.","solutions":["Add the Maven/Gradle dependency that contains the named class and rebuild","Check the class name for typos or package moves (verify with the version of Vert.x/Quarkus you use)","If it is optional functionality, guard/avoid the config or build item that references it","Run ./mvnw dependency:tree to confirm the artifact providing the class is actually resolved"],"exampleFix":"// before (pom.xml): no vertx-web dependency but codec io.vertx.ext.web.* referenced\n// after\n<dependency>\n  <groupId>io.vertx</groupId>\n  <artifactId>vertx-web</artifactId>\n</dependency>","handlingStrategy":"validation","validationCode":"try {\n    Class.forName(name, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Add the dependency providing \" + name, e);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add every Vert.x module your configured class names reference before building","Run ./mvnw dependency:tree when a type fails to load","Verify class names against the exact Vert.x version in use","Avoid hardcoding class names from optional dependencies"],"tags":["quarkus","vertx","classpath","classnotfound","build-time"],"backgroundTag":"classnotfound-at-build-time","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}