quarkusio/quarkus · error · IllegalStateException

Could not initialize mapped class ${className}

Error message

Could not initialize mapped class ${className}

What it means

At static-init/recording time, the recorder loads each class that carries a Hibernate Search root mapping annotation (@Indexed, @SearchExtension target entity, etc.) via Class.forName with the TCCL. If a class cannot be found or initialized, it wraps the failure in an IllegalStateException naming the class. This typically means a mapped entity is missing at runtime or its static initializer failed.

Source

Thrown at extensions/hibernate-search-orm-elasticsearch/runtime/src/main/java/io/quarkus/hibernate/search/orm/elasticsearch/runtime/HibernateSearchElasticsearchRecorder.java:74

    public HibernateSearchElasticsearchRecorder(
            final HibernateSearchElasticsearchBuildTimeConfig buildTimeConfig,
            final RuntimeValue<HibernateSearchElasticsearchRuntimeConfig> runtimeConfig) {
        this.buildTimeConfig = buildTimeConfig;
        this.runtimeConfig = runtimeConfig;
    }

    public HibernateOrmIntegrationStaticInitListener createStaticInitListener(
            HibernateSearchOrmElasticsearchMapperContext mapperContext,
            Set<String> rootAnnotationMappedClassNames,
            List<HibernateOrmIntegrationStaticInitListener> integrationStaticInitListeners) {
        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);
            }
        }
        return new HibernateSearchIntegrationStaticInitListener(mapperContext,
                buildTimeConfig.persistenceUnits().get(mapperContext.persistenceUnitName),
                rootAnnotationMappedClasses,
                integrationStaticInitListeners);
    }

    public HibernateOrmIntegrationStaticInitListener createStaticInitInactiveListener() {
        return new HibernateSearchIntegrationStaticInitInactiveListener();
    }

    public HibernateOrmIntegrationRuntimeInitListener createRuntimeInitListener(
            HibernateSearchOrmElasticsearchMapperContext mapperContext,
            List<HibernateOrmIntegrationRuntimeInitListener> integrationRuntimeInitListeners) {
        HibernateSearchElasticsearchRuntimeConfigPersistenceUnit puConfig = runtimeConfig.getValue()
                .persistenceUnits()
                .get(mapperContext.persistenceUnitName);

View on GitHub (pinned to e1c734241f)

Solutions

1. Do a clean rebuild (mvn clean install / gradle clean build) to refresh the recorded mapped-class list after refactoring entities
2. Inspect the wrapped cause (e) printed with this error — fix the underlying NoClassDefFoundError or ExceptionInInitializerError it reports
3. Restore the missing class/jar on the runtime classpath or remove the stale @Indexed mapping
4. In dev mode, restart Quarkus (or use live reload) to clear stale recorded state

Example fix

// before: stale build after renaming com.acme.Book -> com.acme.Item
mvn quarkus:dev
// after
clean rebuild: mvn clean compile quarkus:dev (recorded class names refreshed)

try {
  // app startup / static init
} catch (IllegalStateException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Could not initialize mapped class ")) {
    log.errorf(e.getCause(), "Fix the mapped entity class or clean-rebuild: %s", e.getMessage());
    throw e; // startup cannot proceed safely
  }
  throw e;
}

When it happens

Trigger: Runtime (static init): one of rootAnnotationMappedClassNames recorded at build time cannot be loaded/initialized by Class.forName(className, true, tccl) — e.g. the class was removed or refactored after the build, a static initializer threw, or an dependency of the class is missing from the runtime classpath (including native-image scenarios).

Common situations: Renaming/deleting an @Indexed entity without a clean rebuild (stale recorded class list); a static init block in the entity throwing an exception; a dependency providing a mapped class missing at runtime; hot-reload (dev mode) inconsistencies after refactoring.

Related errors

• Dev services for ${request.getName()} requires a startable s
• Invalid proxy passed to recorder. ${rp} was created in a run
• Quarkus manual bootstrap failed
• Command line arguments not available during static init
• This cache is not an instance of

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