quarkusio/quarkus · error · IllegalStateException

Unable to load type: ${name}

Error message

Unable to load type: ${name}

What it means

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.

Source

Thrown at extensions/vertx/deployment/src/main/java/io/quarkus/vertx/deployment/VertxProcessor.java:287

    @BuildStep
    NativeImageConfigBuildItem reinitializeClassesForNetty() {
        NativeImageConfigBuildItem.Builder builder = NativeImageConfigBuildItem.builder();

        builder.addRuntimeInitializedClass("io.vertx.core.http.impl.http1.Http1ServerResponse")
                .addRuntimeInitializedClass("io.vertx.core.parsetools.impl.RecordParserImpl");

        if (QuarkusClassLoader.isClassPresentAtRuntime("io.vertx.ext.web.client.impl.MultipartFormUpload")) {
            builder.addRuntimeInitializedClass("io.vertx.ext.web.client.impl.MultipartFormUpload");
        }

        return builder.build();
    }

    private Class<?> tryLoad(String name, ClassLoader tccl) {
        try {
            return tccl.loadClass(name);
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException("Unable to load type: " + name, e);
        }
    }

    @BuildStep
    void registerNativeImageResources(BuildProducer<NativeImageResourceBuildItem> resources,
            BuildProducer<ServiceProviderBuildItem> serviceProviders) {
        // Accessed by io.vertx.core.impl.VertxBuilder.<init> via ServiceLoader
        serviceProviders.produce(ServiceProviderBuildItem.allProvidersFromClassPath(VertxServiceProvider.class.getName()));
        // Accessed by io.vertx.core.impl.VertxImpl.<init>
        resources.produce(new NativeImageResourceBuildItem("META-INF/services/io.vertx.core.spi.VerticleFactory"));
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the Maven/Gradle dependency that contains the named class and rebuild
2. Check the class name for typos or package moves (verify with the version of Vert.x/Quarkus you use)
3. If it is optional functionality, guard/avoid the config or build item that references it
4. Run ./mvnw dependency:tree to confirm the artifact providing the class is actually resolved

Example fix

// before (pom.xml): no vertx-web dependency but codec io.vertx.ext.web.* referenced
// after
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-web</artifactId>
</dependency>

try {
    Class.forName(name, false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Add the dependency providing " + name, e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to load the datasource driver <driverName> for the <f
• Unable to load the config property type: ${className}
• Injected class not found in index:
• Thread pool class not found: ${threadPoolClass}
• Cannot load task class: {taskClass}

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/1a96f799f6d5679f. Report an issue: GitHub.