{"record":{"id":"114cee250b32a93e","repo":"quarkusio/quarkus","slug":"could-not-initialize-mapped-class-classname-114cee","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-standalone-elasticsearch/runtime/src/main/java/io/quarkus/hibernate/search/standalone/elasticsearch/runtime/HibernateSearchStandaloneRecorder.java","lineNumber":64,"sourceCode":"    private final HibernateSearchStandaloneBuildTimeConfig buildTimeConfig;\n    private final RuntimeValue<HibernateSearchStandaloneRuntimeConfig> runtimeConfig;\n\n    public HibernateSearchStandaloneRecorder(\n            final HibernateSearchStandaloneBuildTimeConfig buildTimeConfig,\n            final RuntimeValue<HibernateSearchStandaloneRuntimeConfig> runtimeConfig) {\n        this.buildTimeConfig = buildTimeConfig;\n        this.runtimeConfig = runtimeConfig;\n    }\n\n    public void preBoot(HibernateSearchStandaloneElasticsearchMapperContext mapperContext,\n            Set<String> rootAnnotationMappedClassNames) {\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        Map<String, Object> bootProperties = new LinkedHashMap<>();\n        new StaticInitListener(mapperContext, buildTimeConfig, rootAnnotationMappedClasses)\n                .contributeBootProperties(bootProperties::put);\n        StandalonePojoIntegrationBooter booter = StandalonePojoIntegrationBooter.builder()\n                .properties(bootProperties)\n                // MethodHandles don't work at all in GraalVM 20 and below, and seem unreliable on GraalVM 21\n                .valueReadHandleFactory(ValueHandleFactory.usingJavaLangReflect())\n                // Integrate CDI\n                .property(StandalonePojoMapperSpiSettings.BEAN_PROVIDER, new ArcBeanProvider(Arc.container()))\n                .build();\n        booter.preBoot(bootProperties::put);\n        HibernateSearchStandalonePreBootState.set(bootProperties);\n    }\n\n    public void checkNoExplicitActiveTrue() {\n        if (runtimeConfig.getValue().active().orElse(false)) {","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-search-standalone-elasticsearch/runtime/src/main/java/io/quarkus/hibernate/search/standalone/elasticsearch/runtime/HibernateSearchStandaloneRecorder.java#L46-L82","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the 'Caused by' of this exception — it names the real failure (ClassNotFoundException, NoClassDefFoundError, ExceptionInInitializerError) and fix that root cause.","Run a clean build (mvn clean install / quarkus dev) to remove stale generated indexes referencing old class names.","Ensure the class named in the message actually exists on the runtime classpath and all its static dependencies are present.","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)."],"exampleFix":"// before: class renamed but annotation list references old name\n// build-time recorded: com.app.OldEntity  -> ClassNotFoundException\npublic class NewEntity { @Id long id; }\n\n// after: rebuild so preBoot records the current class\n// mvn clean install  and ensure the class is annotated/discovered:\n@SearchableEntity\npublic class NewEntity { @Id long id; }","handlingStrategy":"try-catch","validationCode":"// Pre-check that all mapped classes can be loaded before boot:\nfor (String className : rootAnnotationMappedClassNames) {\n    try {\n        Class.forName(className, false, Thread.currentThread().getContextClassLoader());\n    } catch (Throwable t) {\n        throw new IllegalStateException(\"Mapped class not loadable before boot: \" + className, t);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    recorder.preBoot(...);\n} catch (IllegalStateException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Could not initialize mapped class\")) {\n        Throwable root = e.getCause(); // ClassNotFoundException / ExceptionInInitializerError\n        LOGGER.errorf(root, \"Fix class %s on the runtime classpath\", e.getMessage());\n    }\n    throw e;\n}","preventionTips":["Run mvn clean after renaming/removing mapped entity classes to purge stale build records.","Keep static initializers of mapped classes side-effect free (no I/O or throwing config lookups in clinit).","Verify runtime classpath includes every artifact that hosts annotated mapped classes."],"tags":["quarkus","hibernate-search","classloading","startup"],"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-12T22:17:10.623Z"}