{"record":{"id":"3c32fd74abffbc1d","repo":"hibernate/hibernate-orm","slug":"unable-to-instantiate-scanningprovider-s-3c32fd","errorCode":null,"errorMessage":"Unable to instantiate ScanningProvider `%s`","messagePattern":"Unable to instantiate ScanningProvider `(.+?)`","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/jpa/boot/spi/PersistenceConfigurationDescriptor.java","lineNumber":317,"sourceCode":"\n\tprivate static ScanningProvider determineScanningProviderFromSetting(\n\t\t\t@Nonnull ConfigurationService configurationService,\n\t\t\t@Nonnull ClassLoaderService classLoaderService) {\n\t\tvar providerSetting = configurationService.getSettings().get( PersistenceSettings.SCANNING );\n\t\tif ( providerSetting == null ) {\n\t\t\treturn null;\n\t\t}\n\n\t\t// might be any of the 3 standard forms\n\t\tif ( providerSetting instanceof ScanningProvider instance ) {\n\t\t\treturn instance;\n\t\t}\n\t\telse if ( providerSetting instanceof Class<?> implClass ) {\n\t\t\ttry {\n\t\t\t\treturn (ScanningProvider) implClass.getDeclaredConstructor().newInstance();\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\tString.format( Locale.ROOT,\n\t\t\t\t\t\t\t\t\"Unable to instantiate ScanningProvider `%s`\",\n\t\t\t\t\t\t\t\timplClass.getName()\n\t\t\t\t\t\t),\n\t\t\t\t\t\te\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\tvar implClassName = providerSetting.toString();\n\t\t\tvar implClass = classLoaderService.classForName( implClassName );\n\t\t\ttry {\n\t\t\t\treturn (ScanningProvider) implClass.getDeclaredConstructor().newInstance();\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\tString.format( Locale.ROOT,\n\t\t\t\t\t\t\t\t\"Unable to instantiate ScanningProvider `%s`\",","sourceCodeStart":299,"sourceCodeEnd":335,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/jpa/boot/spi/PersistenceConfigurationDescriptor.java#L299-L335","documentation":"Thrown by PersistenceConfigurationDescriptor.determineScanningProviderFromSetting() as a HibernateException when the class configured via the hibernate.archive.scanning setting (as a Class object) fails to instantiate with getDeclaredConstructor().newInstance(). This means the class was found but its construction broke: missing/inaccessible no-arg constructor, abstract class, or a constructor that threw.","triggerScenarios":"Setting hibernate.archive.scanning to a Class (or letting config binding produce one) whose implementation has no public no-arg constructor, is abstract, or throws from its constructor during EntityManagerFactory bootstrap when the archive scanner is resolved.","commonSituations":"Replacing Hibernate's default entity scanning with a custom ScanningProvider (e.g. to scan a classpath directory or a custom archive layout) without providing a no-arg constructor; constructor performs eager initialization that fails in the boot environment.","solutions":["Add a public no-arg constructor to your ScanningProvider implementation.","Keep the provider stateless at construction; defer any resource acquisition to the scan call.","Verify the class implements org.hibernate.jpa.boot.spi.ScanningProvider and is concrete.","Check the wrapped cause - if the constructor itself threw, fix that initialization code."],"exampleFix":"// before\npublic class FastClasspathScanner implements ScanningProvider {\n    public FastClasspathScanner(Index index) { ... } // only arg ctor\n}\n\n// after\npublic class FastClasspathScanner implements ScanningProvider {\n    public FastClasspathScanner() { }\n    public FastClasspathScanner(Index index) { ... }\n}","handlingStrategy":"validation","validationCode":"Class<?> c = (Class<?>) settings.get(\"hibernate.archive.scanning\");\nif (c != null) c.getDeclaredConstructor().newInstance(); // assert no-arg ctor exists before boot","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep custom ScanningProvider implementations stateless with public no-arg constructors.","Cover custom scanning SPIs with a unit test that reflectively instantiates them."],"tags":["hibernate","jpa","scanning","configuration","instantiation","entity-discovery"],"backgroundTag":"configured-class-instantiation-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}