{"record":{"id":"837d94cbd40e713b","repo":"hibernate/hibernate-orm","slug":"unable-to-instantiate-scanningprovider-s","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/boot/scan/internal/ScanningHelper.java","lineNumber":115,"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":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/scan/internal/ScanningHelper.java#L97-L133","documentation":"During bootstrap Hibernate resolves the configured ScanningProvider (setting 'hibernate.archive.scanning', see PersistenceSettings.SCANNING). The setting may be an instance, a Class, or a class-name String. Here the setting was a Class, so ScanningHelper calls implClass.getDeclaredConstructor().newInstance() reflectively; any failure (missing or inaccessible no-arg constructor, abstract class or interface, constructor that throws, or the created object not being a ScanningProvider causing a ClassCastException) is wrapped in this HibernateException.","triggerScenarios":"Setting PersistenceSettings.SCANNING ('hibernate.archive.scanning') to a Class object whose declared no-arg constructor cannot be invoked: constructor is private/protected, the class is abstract or an interface, the constructor throws (e.g. looks up env/config), or the class does not implement ScanningProvider so the (ScanningProvider) cast fails inside the try block.","commonSituations":"Custom scanning provider that only has constructor-arg constructors; a provider whose no-arg constructor does environment lookups that fail in CI; passing a class that implements the SPI from a different Hibernate version where the interface moved; access-control failure under JPMS because the package is not exported/opened.","solutions":["Give the implementation a public no-arg constructor (or a declared constructor accessible to the caller) so getDeclaredConstructor().newInstance() succeeds.","Pass an instance instead of a Class: builder.applySetting(PersistenceSettings.SCANNING, new MyScanningProvider(...)) - the 'instanceof ScanningProvider' branch returns it directly with no reflection.","Inspect the wrapped cause (e) in the stack trace - InstantiationException means abstract/interface, NoSuchMethodException means no no-arg constructor, ClassCastException means wrong interface, InvocationTargetException means your constructor threw.","Verify the class actually implements org.hibernate.boot.scan.spi.ScanningProvider from the same Hibernate version, and that its module exports the package when running on the module path."],"exampleFix":"// before\nbuilder.applySetting( PersistenceSettings.SCANNING, MyScanningProvider.class );\n// MyScanningProvider(String cfg) only -> no no-arg constructor -> error\n\n// after\npublic MyScanningProvider() {\n    this(defaultConfig());\n}\n// or skip reflection entirely:\nbuilder.applySetting( PersistenceSettings.SCANNING, new MyScanningProvider(cfg) );","handlingStrategy":"validation","validationCode":"Class<?> impl = MyScanningProvider.class;\nif ( !org.hibernate.boot.scan.spi.ScanningProvider.class.isAssignableFrom( impl ) ) {\n    throw new IllegalStateException( impl + \" is not a ScanningProvider\" );\n}\ntry { impl.getDeclaredConstructor(); } // NoSuchMethodException here = would fail in Hibernate\ncatch ( NoSuchMethodException e ) { throw new IllegalStateException( impl + \" needs a no-arg constructor\" ); }","typeGuard":"static boolean instantiableScanningProvider(Object setting) {\n    if ( setting instanceof org.hibernate.boot.scan.spi.ScanningProvider ) return true; // instance form: safe\n    Class<?> c = setting instanceof Class<?> k ? k : null;\n    return c != null\n            && org.hibernate.boot.scan.spi.ScanningProvider.class.isAssignableFrom( c )\n            && java.lang.reflect.Modifier.isPublic( c.getModifiers() );\n}","tryCatchPattern":"try {\n    Metadata metadata = new MetadataSources( ssr ).buildMetadata();\n}\ncatch ( HibernateException e ) {\n    if ( e.getMessage() != null && e.getMessage().startsWith( \"Unable to instantiate ScanningProvider\" ) ) {\n        // e.getCause(): NoSuchMethodException / InstantiationException / InvocationTargetException / ClassCastException\n        throw new BootstrapException( \"Bad hibernate.archive.scanning setting\", e.getCause() );\n    }\n    throw e;\n}","preventionTips":["Prefer passing an instance for hibernate.archive.scanning - the instanceof branch bypasses reflection entirely.","Keep a public no-arg constructor on every provider/scanner class you register; put required setup in static config instead of constructor args.","Assert in unit tests that the provider class has a no-arg constructor and implements the expected SPI interface for the Hibernate version on the classpath."],"tags":["hibernate","bootstrap","scanning","reflection","instantiation"],"backgroundTag":"reflection-instantiation-failure","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}