{"record":{"id":"0e389ee90e5e2740","repo":"hibernate/hibernate-orm","slug":"unable-to-instantiate-specified-statisticsfactory","errorCode":null,"errorMessage":"Unable to instantiate specified StatisticsFactory implementation [{}]","messagePattern":"Unable to instantiate specified StatisticsFactory implementation \\[(.+?)\\]","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsInitiator.java","lineNumber":74,"sourceCode":"\t\tif ( configValue == null ) {\n\t\t\tfinal var discovered = discover( classLoaderService );\n\t\t\treturn discovered != null ? discovered : StatisticsImpl::new;\n\t\t}\n\t\telse if ( configValue instanceof StatisticsFactory factory ) {\n\t\t\treturn factory;\n\t\t}\n\t\telse {\n\t\t\t// assume it names the factory class\n\t\t\ttry {\n\t\t\t\treturn (StatisticsFactory)\n\t\t\t\t\t\tclassLoaderService.classForName( configValue.toString() )\n\t\t\t\t\t\t\t\t.newInstance();\n\t\t\t}\n\t\t\tcatch (HibernateException e) {\n\t\t\t\tthrow e;\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\"Unable to instantiate specified StatisticsFactory implementation [\" + configValue + \"]\",\n\t\t\t\t\t\te\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate static @Nullable StatisticsFactory discover(@Nonnull ClassLoaderService classLoaderService) {\n\t\tfinal var discovered = classLoaderService.loadJavaServices( StatisticsFactory.class );\n\t\tfinal var iterator = discovered.iterator();\n\t\tif ( iterator.hasNext() ) {\n\t\t\tfinal var selected = iterator.next();\n\t\t\tif ( iterator.hasNext() ) {\n\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\"Multiple StatisticsFactory service registrations found via ServiceLoader; \"\n\t\t\t\t\t\t+ \"specify one explicitly via '\" + STATS_BUILDER + \"'\" );\n\t\t\t}\n\t\t\treturn selected;","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsInitiator.java#L56-L92","documentation":"When hibernate.stats.factory names a class, StatisticsInitiator loads it through ClassLoaderService and instantiates it reflectively (Class#newInstance()). Any load or construction failure — class missing from the classpath, no accessible no-arg constructor, abstract/interface class, or a constructor that throws — is wrapped in a HibernateException with this message (a HibernateException raised during the lookup itself is rethrown unchanged, so read the chained cause).","triggerScenarios":"Setting hibernate.stats.factory=org.acme.MetricsStatisticsFactory where the class is not on the runtime classpath, is package-private, lacks a public no-arg constructor, or whose constructor throws (for example it eagerly contacts a metrics registry that is not available at bootstrap).","commonSituations":"Custom StatisticsFactory integrations for Micrometer/Prometheus; fat-jar or application-server module classpath differences between dev and prod; constructors that do eager external work at boot; class renamed or relocated by a shading plugin.","solutions":["Give the class a public no-arg constructor and make sure it implements org.hibernate.stat.spi.StatisticsFactory.","Fix the class name/deployment so the class is visible to Hibernate's ClassLoaderService (check shaded-jar relocations, missing dependency, app-server module visibility).","Read the chained cause via getCause() on the HibernateException and fix the underlying failure (missing constructor dependency, config the constructor reads)."],"exampleFix":"// before\npublic class MetricsStatisticsFactory implements StatisticsFactory {\n    MetricsStatisticsFactory(MeterRegistry registry) { ... } // no no-arg ctor -> instantiation fails\n}\n\n// after\npublic class MetricsStatisticsFactory implements StatisticsFactory {\n    public MetricsStatisticsFactory() { ... } // resolve the registry lazily on first use\n}","handlingStrategy":"try-catch","validationCode":"Class<?> clazz = Class.forName(factoryClassName, false, Thread.currentThread().getContextClassLoader());\nif (!org.hibernate.stat.spi.StatisticsFactory.class.isAssignableFrom(clazz)\n        || clazz.getConstructor() == null) {\n    throw new IllegalStateException(\"hibernate.stats.factory class must implement StatisticsFactory with a no-arg ctor\");\n}","typeGuard":"static boolean usableStatisticsFactory(Class<?> c) {\n    return org.hibernate.stat.spi.StatisticsFactory.class.isAssignableFrom(c)\n            && java.lang.reflect.Modifier.isPublic(c.getModifiers())\n            && !java.lang.reflect.Modifier.isAbstract(c.getModifiers());\n}","tryCatchPattern":"try {\n    sessionFactory = cfg.buildSessionFactory();\n} catch (HibernateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"StatisticsFactory\")) {\n        // read e.getCause(): missing class, bad ctor, or ctor failure\n    }\n    throw e;\n}","preventionTips":["Give every custom StatisticsFactory a public no-arg constructor.","Unit-test reflective instantiation of the factory class in CI (Class.forName(...).getConstructor().newInstance()).","Keep constructors lazy — no eager external connections at bootstrap."],"tags":["hibernate","statistics","reflection","class-instantiation","configuration"],"backgroundTag":"class-instantiation-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}