{"record":{"id":"5bb51273b4452c72","repo":"hibernate/hibernate-orm","slug":"unable-to-load-class-classname","errorCode":null,"errorMessage":"Unable to load class [\" + className + \"]","messagePattern":"Unable to load class \\[\" \\+ className \\+ \"\\]","errorType":"exception","errorClass":"ClassLoadingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/internal/ClassLoaderServiceImpl.java","lineNumber":93,"sourceCode":"\t\t}\n\n\t\t// normalize adding known class-loaders...\n\t\t// then the Hibernate class loader\n\t\torderedClassLoaderSet.add( ClassLoaderServiceImpl.class.getClassLoader() );\n\n\t\t// now build the aggregated class loader...\n\t\tthis.aggregatedClassLoader = new AggregatedClassLoader( orderedClassLoaderSet, lookupPrecedence );\n\t}\n\n\t@Override\n\t@SuppressWarnings(\"unchecked\")\n\t@Nonnull\n\tpublic <T> Class<T> classForName(@Nonnull String className) {\n\t\ttry {\n\t\t\treturn (Class<T>) Class.forName( className, true, getAggregatedClassLoader() );\n\t\t}\n\t\tcatch (Exception | LinkageError e) {\n\t\t\tthrow new ClassLoadingException( \"Unable to load class [\" + className + \"]\", e );\n\t\t}\n\t}\n\n\t@Override\n\t@Nullable\n\tpublic URL locateResource(@Nonnull String name) {\n\t\t// first we try name as a URL\n\t\ttry {\n\t\t\treturn new URL( name );\n\t\t}\n\t\tcatch (Exception ignore) {\n\t\t}\n\n\t\t// if we couldn't find the resource containing a classpath:// prefix above, that means we don't have a URL\n\t\t// handler for it. So let's remove the prefix and resolve against our class loader.\n\t\tname = stripClasspathScheme( name );\n\n\t\ttry {","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/registry/classloading/internal/ClassLoaderServiceImpl.java#L75-L111","documentation":"classForName() runs Class.forName(className, true, aggregatedClassLoader) across Hibernate's aggregated class loader (Hibernate's own loader plus the thread-context loader per the configured precedence). Any failure - ClassNotFoundException, NoClassDefFoundError, ExceptionInInitializerError from static initializers, or other LinkageError - is wrapped in a ClassLoadingException carrying the class name. This is Hibernate's single choke point for name-to-Class resolution used by settings, dialect/strategy lookup, and entity reflection.","triggerScenarios":"Any Hibernate setting or API that takes a class name: hibernate.dialect=my.CustomDialect, a custom ConnectionProvider/UserType/IdentifierGenerator class, StrategySelector.selectStrategyImplementor, or class metadata loading when the named class is not loadable by any of the aggregated loaders.","commonSituations":"Missing jar on the runtime classpath (provided-scope dependency not shipped); typo in a fully-qualified class name; duplicated or older jar versions hiding the class; app-server / fat-jar / shaded-jar classloader visibility problems; GraalVM native image missing reflection metadata; a static initializer of the class throwing.","solutions":["Verify the fully-qualified class name has no typos and matches the library version you actually ship","Add the jar containing the class to the runtime classpath (check dependency scope and packaging steps)","Run mvn dependency:tree / gradle dependencies and deduplicate conflicting versions of the artifact","In containers/app servers, set hibernate.classLoader.tccl_lookup_precedence to never or before so the intended classloader wins","For native images, register the class for reflection (reflection-config / @RegisterReflectionForBinding)"],"exampleFix":"// before\n<property name=\"hibernate.dialect\" value=\"org.hibernate.dialect.PostgresSQLDialect\"/> <!-- typo -->\n\n// after\n<property name=\"hibernate.dialect\" value=\"org.hibernate.dialect.PostgreSQLDialect\"/>","handlingStrategy":"validation","validationCode":"// Probe class references before boot\nString dialectName = config.get(\"hibernate.dialect\");\ntry {\n    Class.forName(dialectName, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Configured class not on classpath: \" + dialectName, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    return classLoaderService.classForName(className);\n} catch (ClassLoadingException e) {\n    Throwable cause = e.getCause(); // ClassNotFoundException / LinkageError - the real reason\n    log.warn(\"Cannot load {} ({}); check classpath and dependency scope\", className, cause);\n    throw e;\n}","preventionTips":["Ship a startup probe that Class.forName-loads every class referenced in Hibernate properties","Keep a single consistent Hibernate version across modules; run dependency:tree in CI","For native images, generate reflection metadata for all reflectively loaded classes"],"tags":["hibernate","classloading","classpath","configuration","dependency"],"backgroundTag":"class-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}