quarkusio/quarkus · error · IllegalStateException

The class (${className}) cannot be found during deployment.

Error message

The class (${className}) cannot be found during deployment.

What it means

StandardMethodImplementor builds OpenAPI/Gizmo annotations at deployment time and needs to load classes by name from the deployment classloader. If Thread.currentThread().getContextClassLoader().loadClass(className) cannot resolve the class, the build aborts with this IllegalStateException. It indicates a type referenced by the generated resource (e.g. an OpenAPI schema type, a java type like BigDecimal, or an entity/ID type) is not visible during augmentation.

Source

Thrown at extensions/panache/rest-data-panache/deployment/src/main/java/io/quarkus/rest/data/panache/deployment/methods/StandardMethodImplementor.java:260

    protected boolean hasValidatorCapability() {
        return capabilities.isPresent(Capability.HIBERNATE_VALIDATOR);
    }

    protected boolean isNotReactivePanache() {
        return !capabilities.isPresent(Capability.HIBERNATE_REACTIVE);
    }

    private static Enum schemaTypeArray() {
        Class<?> schemaTypeClass = toClass(SCHEMA_TYPE_CLASS_NAME);
        return Enum.valueOf((Class<Enum>) schemaTypeClass, SCHEMA_TYPE_ARRAY);
    }

    private static Class<?> toClass(String className) {
        ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
        try {
            return classLoader.loadClass(className);
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException("The class (" + className + ") cannot be found during deployment.", e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the missing dependency containing the named class to the application so it is present at deployment time.
2. Check the class name in the message for typos or wrong packages in schema/OpenAPI annotations.
3. Ensure the type is in a normal application (runtime) artifact, not an excluded/optional one.
4. If you changed this extension code, verify you load via the proper Quarkus deployment classloader (e.g. ClassLoader.getSystemClassLoader or the app-classloader BuildItem) rather than the TCCL.

Example fix

// before: type not on classpath
@Schema(implementation = com.acme.NotIncludedDto.class)
// after: add the dependency, or reference a resolvable type
<dependency>com.acme:acme-dto</dependency>
@Schema(implementation = com.acme.IncludedDto.class)

// before relying on a type in schema/OpenAPI metadata
try {
    Class.forName("com.acme.SomeDto", false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Dependency containing com.acme.SomeDto is missing from the deployment classpath");
}

When it happens

Trigger: Deployment time while generating a resource method's OpenAPI response annotation or resolving a schema type: toClass() is called with a class name (from addOpenApiResponseAnnotation or schemaTypeClass) that is not on the deployment classpath — e.g. a custom type referenced by the entity, a wrong fully-qualified name in a schema annotation, or a required extension jar absent.

Common situations: Entity or ID fields use types from a library not on the compile/deploy classpath; typos in @Schema(implementation=...) strings; missing dependency (e.g. java-money, custom DTO module) so the OpenAPI schema type cannot be loaded; split-package/classloading surprises in custom deployment code.

Related errors

• REST Data Panache can only work if 'quarkus-rest' or 'quarku
• Reactive REST Data Panache does not work with 'quarkus-reste
• Cannot generate HAL endpoints without either 'quarkus-restea
• Cannot generate HAL endpoints without either 'quarkus-rest-j
• Unsupported object of type ${object.getClass()}. Supported t

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