quarkusio/quarkus · error · IllegalStateException

Could not initialize mapped class ${className}

Error message

Could not initialize mapped class ${className}

What it means

During Hibernate Search Standalone startup, HibernateSearchStandaloneRecorder.preBoot loads each mapped class by name through Class.forName(className, true, tccl) using the thread context class loader. If any class cannot be loaded or initialized (class missing, static initializer throwing, linkage error), the recorder wraps the failure in an IllegalStateException("Could not initialize mapped class " + className, e).

Source

Thrown at extensions/hibernate-search-standalone-elasticsearch/runtime/src/main/java/io/quarkus/hibernate/search/standalone/elasticsearch/runtime/HibernateSearchStandaloneRecorder.java:64

    private final HibernateSearchStandaloneBuildTimeConfig buildTimeConfig;
    private final RuntimeValue<HibernateSearchStandaloneRuntimeConfig> runtimeConfig;

    public HibernateSearchStandaloneRecorder(
            final HibernateSearchStandaloneBuildTimeConfig buildTimeConfig,
            final RuntimeValue<HibernateSearchStandaloneRuntimeConfig> runtimeConfig) {
        this.buildTimeConfig = buildTimeConfig;
        this.runtimeConfig = runtimeConfig;
    }

    public void preBoot(HibernateSearchStandaloneElasticsearchMapperContext mapperContext,
            Set<String> rootAnnotationMappedClassNames) {
        Set<Class<?>> rootAnnotationMappedClasses = new LinkedHashSet<>();
        ClassLoader tccl = Thread.currentThread().getContextClassLoader();
        for (String className : rootAnnotationMappedClassNames) {
            try {
                rootAnnotationMappedClasses.add(Class.forName(className, true, tccl));
            } catch (Exception e) {
                throw new IllegalStateException("Could not initialize mapped class " + className, e);
            }
        }
        Map<String, Object> bootProperties = new LinkedHashMap<>();
        new StaticInitListener(mapperContext, buildTimeConfig, rootAnnotationMappedClasses)
                .contributeBootProperties(bootProperties::put);
        StandalonePojoIntegrationBooter booter = StandalonePojoIntegrationBooter.builder()
                .properties(bootProperties)
                // MethodHandles don't work at all in GraalVM 20 and below, and seem unreliable on GraalVM 21
                .valueReadHandleFactory(ValueHandleFactory.usingJavaLangReflect())
                // Integrate CDI
                .property(StandalonePojoMapperSpiSettings.BEAN_PROVIDER, new ArcBeanProvider(Arc.container()))
                .build();
        booter.preBoot(bootProperties::put);
        HibernateSearchStandalonePreBootState.set(bootProperties);
    }

    public void checkNoExplicitActiveTrue() {
        if (runtimeConfig.getValue().active().orElse(false)) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Read the 'Caused by' of this exception — it names the real failure (ClassNotFoundException, NoClassDefFoundError, ExceptionInInitializerError) and fix that root cause.
2. Run a clean build (mvn clean install / quarkus dev) to remove stale generated indexes referencing old class names.
3. Ensure the class named in the message actually exists on the runtime classpath and all its static dependencies are present.
4. If a static initializer throws, debug the clinit of that class so it does not throw at class-init time (no external calls/failing config in static blocks).

Example fix

// before: class renamed but annotation list references old name
// build-time recorded: com.app.OldEntity  -> ClassNotFoundException
public class NewEntity { @Id long id; }

// after: rebuild so preBoot records the current class
// mvn clean install  and ensure the class is annotated/discovered:
@SearchableEntity
public class NewEntity { @Id long id; }

// Pre-check that all mapped classes can be loaded before boot:
for (String className : rootAnnotationMappedClassNames) {
    try {
        Class.forName(className, false, Thread.currentThread().getContextClassLoader());
    } catch (Throwable t) {
        throw new IllegalStateException("Mapped class not loadable before boot: " + className, t);
    }
}

try {
    recorder.preBoot(...);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Could not initialize mapped class")) {
        Throwable root = e.getCause(); // ClassNotFoundException / ExceptionInInitializerError
        LOGGER.errorf(root, "Fix class %s on the runtime classpath", e.getMessage());
    }
    throw e;
}

When it happens

Trigger: preBoot receiving a rootAnnotationMappedClassNames entry (classes annotated with Hibernate Search Standalone mapping annotations such as @SearchMapping-related roots) that fails Class.forName with initialize=true under the TCCL — e.g. ClassNotFoundException after a changed artifact, NoClassDefFoundError for a missing dependency, or ExceptionInInitializerError from a failing static block.

Common situations: Renaming or deleting an entity class recorded at build time while stale build output persists; a mapped class's static initializer throwing (bad config read, external service in clinit); native-image/Quarkus classloading issues where the class is in a different classloader; a dependency that provides a supertype of the class is missing at runtime.

Related errors

• Failed to load steps from %s
• The class (${name}) cannot be created during deployment.
• The class (${name}) cannot be created during deployment.
• Unable to find main method on class '${originalMainClassName
• Unknown class: ${token}

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