{"record":{"id":"1e32dfbb6d58aeec","repo":"hibernate/hibernate-orm","slug":"can-t-load-class","errorCode":null,"errorMessage":"Can't load class: {}","messagePattern":"Can't load class: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java","lineNumber":1720,"sourceCode":"\t\tfinal Class<? extends T> instanceClass;\n\t\tif ( clazz.isInstance( settingValue ) ) {\n\t\t\treturn clazz.cast( settingValue );\n\t\t}\n\t\telse if ( settingValue instanceof Class ) {\n\t\t\tinstanceClass = (Class<? extends T>) settingValue;\n\t\t}\n\t\telse if ( settingValue instanceof String className ) {\n\t\t\tif ( standardServiceRegistry != null ) {\n\t\t\t\tinstanceClass =\n\t\t\t\t\t\tstandardServiceRegistry.requireService( ClassLoaderService.class )\n\t\t\t\t\t\t\t\t.classForName( className );\n\t\t\t}\n\t\t\telse {\n\t\t\t\ttry {\n\t\t\t\t\tinstanceClass = (Class<? extends T>) Class.forName( className );\n\t\t\t\t}\n\t\t\t\tcatch (ClassNotFoundException e) {\n\t\t\t\t\tthrow new IllegalArgumentException( \"Can't load class: \" + className, e );\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\tthrow new IllegalArgumentException( \"The provided \" + settingName\n\t\t\t\t\t+ \" setting value [\" + settingValue + \"] is not supported\" );\n\t\t}\n\n\t\tif ( instanceClass != null ) {\n\t\t\ttry {\n\t\t\t\treturn instanceClass.newInstance();\n\t\t\t}\n\t\t\tcatch (InstantiationException | IllegalAccessException e) {\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\t\"The \" + clazz.getSimpleName() +\" class [\" + instanceClass + \"] could not be instantiated\",\n\t\t\t\t\t\te\n\t\t\t\t);\n\t\t\t}","sourceCodeStart":1702,"sourceCodeEnd":1738,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java#L1702-L1738","documentation":"Thrown by EntityManagerFactoryBuilderImpl.loadSettingInstance() as an IllegalArgumentException when a configuration setting that must resolve to a class (e.g. an Interceptor, SessionFactoryObserver, or similar strategy) is given as a String class name and Class.forName() cannot find it. It only occurs on the code path where the standardServiceRegistry is not yet available, so the plain system ClassLoader is used. The missing class name is included in the message.","triggerScenarios":"Passing a misspelled or non-fully-qualified class name in a setting consumed by loadSettingInstance (for example an interceptor/observer setting supplied via configurationValues) when the service registry is null during early boot; the class exists but sits in a jar not visible to the application classloader.","commonSituations":"Typo in a fully-qualified class name in persistence.xml or a properties map; refactoring moved/renamed the class but the config string was not updated; the implementation jar was declared provided-scope and is absent at runtime.","solutions":["Copy the exact fully-qualified class name from the message and verify it against your class (no typos, correct package).","Ensure the jar containing the class is on the runtime classpath (not provided/compile-only).","Prefer passing a Class instance or a pre-built instance in programmatic configuration instead of a String name.","If the class is loaded by a child classloader, pass the instance directly so Class.forName on the app classloader is bypassed."],"exampleFix":"// before\nprops.put(\"hibernate.session_factory.session_scoped_interceptor\", \"com.acme.MyIntercepter\"); // typo\n\n// after\nprops.put(\"hibernate.session_factory.session_scoped_interceptor\", \"com.acme.MyInterceptor\");","handlingStrategy":"validation","validationCode":"// fail early with your own message instead of during bootstrap\nString fqcn = (String) settings.get(SETTING_KEY);\ntry {\n    Class.forName(fqcn, true, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException cnfe) {\n    throw new IllegalStateException(\"Setting \" + SETTING_KEY + \" points to missing class \" + fqcn, cnfe);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Reference class names via ClassName.class.getName() constants instead of string literals so renames stay in sync.","Keep implementation classes in the same artifact that declares the Hibernate config."],"tags":["hibernate","jpa","classloading","configuration","classnotfound"],"backgroundTag":"class-not-found-configuration","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}