{"record":{"id":"10f9784414eb895b","repo":"hibernate/hibernate-orm","slug":"unable-to-instantiate-scanner-s","errorCode":null,"errorMessage":"Unable to instantiate Scanner `%s`","messagePattern":"Unable to instantiate Scanner `(.+?)`","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/scan/internal/ScanningHelper.java","lineNumber":159,"sourceCode":"\n\tprivate static Scanner determineScannerFromSetting(\n\t\t\t@Nonnull ConfigurationService configurationService,\n\t\t\t@Nonnull ClassLoaderService classLoaderService) {\n\t\tvar setting = configurationService.getSettings().get( PersistenceSettings.SCANNER );\n\t\tif ( setting == null ) {\n\t\t\treturn null;\n\t\t}\n\n\t\t// might be any of the 3 standard forms\n\t\tif ( setting instanceof Scanner instance ) {\n\t\t\treturn instance;\n\t\t}\n\t\telse if ( setting instanceof Class<?> implClass ) {\n\t\t\ttry {\n\t\t\t\treturn (Scanner) 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 Scanner `%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 = setting.toString();\n\t\t\tvar implClass = classLoaderService.classForName( implClassName );\n\t\t\ttry {\n\t\t\t\treturn (Scanner) 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 Scanner `%s`\",","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/scan/internal/ScanningHelper.java#L141-L177","documentation":"Hibernate resolves the configured Scanner (PersistenceSettings.SCANNER, 'hibernate.archive.scanner') during bootstrap. The setting can be an instance, a Class, or a String. This throw comes from the Class branch: determineScannerFromSetting calls implClass.getDeclaredConstructor().newInstance() and the call failed (no accessible no-arg constructor, abstract/interface class, constructor threw) or the result could not be cast to Scanner.","triggerScenarios":"Setting 'hibernate.archive.scanner' to a Class object that lacks an invokable declared no-arg constructor, is abstract or an interface, whose constructor throws, or that does not implement org.hibernate.boot.scan.spi.Scanner.","commonSituations":"Registering a custom Scanner implementation (e.g. a virtual-archive / special-packaging scanner) that only has constructors taking arguments; scanner constructor reading a system property that is absent in production; module-path deployment where reflection on the package is not opened.","solutions":["Add a public no-arg constructor to the Scanner implementation.","Register an instance instead of the Class: the 'setting instanceof Scanner' branch accepts it without reflection.","Examine the cause 'e': NoSuchMethodException -> add ctor; InstantiationException -> abstract/interface; InvocationTargetException -> fix your constructor's own failure; ClassCastException -> implement org.hibernate.boot.scan.spi.Scanner.","Prefer PersistenceSettings.SCANNING with a ScanningProvider per its apiNote, which is the supported extension point."],"exampleFix":"// before\nsettings.put( PersistenceSettings.SCANNER, ArchiveScanner.class ); // only ctor: ArchiveScanner(Path)\n\n// after\npublic ArchiveScanner() { this(Paths.get(System.getProperty(\"archive.root\"))); }\n// or pass an instance\nsettings.put( PersistenceSettings.SCANNER, new ArchiveScanner(archiveRoot) );","handlingStrategy":"validation","validationCode":"Class<?> impl = ArchiveScanner.class;\nassert org.hibernate.boot.scan.spi.Scanner.class.isAssignableFrom( impl ) : \"not a Scanner\";\ntry { impl.getDeclaredConstructor(); }\ncatch ( NoSuchMethodException e ) { throw new IllegalStateException( \"Scanner needs a no-arg constructor\", e ); }","typeGuard":"static boolean safeScannerSetting(Object setting) {\n    return setting instanceof org.hibernate.boot.scan.spi.Scanner // instance\n            || ( setting instanceof Class<?> c\n                 && org.hibernate.boot.scan.spi.Scanner.class.isAssignableFrom( c ) );\n}","tryCatchPattern":"try { MetadataSources sources = new MetadataSources( ssr ); }\ncatch ( HibernateException e ) {\n    if ( e.getMessage() != null && e.getMessage().startsWith( \"Unable to instantiate Scanner\" ) ) {\n        // inspect cause: constructor missing vs constructor threw vs wrong type\n    }\n    throw e;\n}","preventionTips":["Register a Scanner instance instead of a Class to skip reflection.","Add a no-arg-constructor unit test for every class you reference in hibernate.archive.scanner.","Prefer the documented SCANNING (provider) extension point unless you truly need to swap the whole Scanner."],"tags":["hibernate","bootstrap","scanner","reflection","instantiation"],"backgroundTag":"reflection-instantiation-failure","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}