{"record":{"id":"ba2e5f8bcf66db19","repo":"quarkusio/quarkus","slug":"could-not-initialize-mapped-class-classname","errorCode":null,"errorMessage":"Could not initialize mapped class ${className}","messagePattern":"Could not initialize mapped class (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-search-orm-elasticsearch/runtime/src/main/java/io/quarkus/hibernate/search/orm/elasticsearch/runtime/HibernateSearchElasticsearchRecorder.java","lineNumber":74,"sourceCode":"\n    public HibernateSearchElasticsearchRecorder(\n            final HibernateSearchElasticsearchBuildTimeConfig buildTimeConfig,\n            final RuntimeValue<HibernateSearchElasticsearchRuntimeConfig> runtimeConfig) {\n        this.buildTimeConfig = buildTimeConfig;\n        this.runtimeConfig = runtimeConfig;\n    }\n\n    public HibernateOrmIntegrationStaticInitListener createStaticInitListener(\n            HibernateSearchOrmElasticsearchMapperContext mapperContext,\n            Set<String> rootAnnotationMappedClassNames,\n            List<HibernateOrmIntegrationStaticInitListener> integrationStaticInitListeners) {\n        Set<Class<?>> rootAnnotationMappedClasses = new LinkedHashSet<>();\n        ClassLoader tccl = Thread.currentThread().getContextClassLoader();\n        for (String className : rootAnnotationMappedClassNames) {\n            try {\n                rootAnnotationMappedClasses.add(Class.forName(className, true, tccl));\n            } catch (Exception e) {\n                throw new IllegalStateException(\"Could not initialize mapped class \" + className, e);\n            }\n        }\n        return new HibernateSearchIntegrationStaticInitListener(mapperContext,\n                buildTimeConfig.persistenceUnits().get(mapperContext.persistenceUnitName),\n                rootAnnotationMappedClasses,\n                integrationStaticInitListeners);\n    }\n\n    public HibernateOrmIntegrationStaticInitListener createStaticInitInactiveListener() {\n        return new HibernateSearchIntegrationStaticInitInactiveListener();\n    }\n\n    public HibernateOrmIntegrationRuntimeInitListener createRuntimeInitListener(\n            HibernateSearchOrmElasticsearchMapperContext mapperContext,\n            List<HibernateOrmIntegrationRuntimeInitListener> integrationRuntimeInitListeners) {\n        HibernateSearchElasticsearchRuntimeConfigPersistenceUnit puConfig = runtimeConfig.getValue()\n                .persistenceUnits()\n                .get(mapperContext.persistenceUnitName);","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-search-orm-elasticsearch/runtime/src/main/java/io/quarkus/hibernate/search/orm/elasticsearch/runtime/HibernateSearchElasticsearchRecorder.java#L56-L92","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Do a clean rebuild (mvn clean install / gradle clean build) to refresh the recorded mapped-class list after refactoring entities","Inspect the wrapped cause (e) printed with this error — fix the underlying NoClassDefFoundError or ExceptionInInitializerError it reports","Restore the missing class/jar on the runtime classpath or remove the stale @Indexed mapping","In dev mode, restart Quarkus (or use live reload) to clear stale recorded state"],"exampleFix":"// before: stale build after renaming com.acme.Book -> com.acme.Item\nmvn quarkus:dev\n// after\nclean rebuild: mvn clean compile quarkus:dev (recorded class names refreshed)","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  // app startup / static init\n} catch (IllegalStateException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Could not initialize mapped class \")) {\n    log.errorf(e.getCause(), \"Fix the mapped entity class or clean-rebuild: %s\", e.getMessage());\n    throw e; // startup cannot proceed safely\n  }\n  throw e;\n}","preventionTips":["Clean rebuild after renaming, moving, or deleting @Indexed entities","Keep entity static initializers trivial (no IO, no failing lookups)","Check the root cause attached to this IllegalStateException first — it names the real problem","In dev mode, restart after large refactorings to clear stale recorded state"],"tags":["quarkus","hibernate-search","class-initialization","static-init","illegal-state"],"backgroundTag":"class-initialization-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}