hibernate/hibernate-orm · error · HibernateException

Unable to instantiate Scanner `%s`

Error message

Unable to instantiate Scanner `%s`

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/scan/internal/ScanningHelper.java:159

	private static Scanner determineScannerFromSetting(
			@Nonnull ConfigurationService configurationService,
			@Nonnull ClassLoaderService classLoaderService) {
		var setting = configurationService.getSettings().get( PersistenceSettings.SCANNER );
		if ( setting == null ) {
			return null;
		}

		// might be any of the 3 standard forms
		if ( setting instanceof Scanner instance ) {
			return instance;
		}
		else if ( setting instanceof Class<?> implClass ) {
			try {
				return (Scanner) implClass.getDeclaredConstructor().newInstance();
			}
			catch (Exception e) {
				throw new HibernateException(
						String.format( Locale.ROOT,
								"Unable to instantiate Scanner `%s`",
								implClass.getName()
						),
						e
				);
			}
		}
		else {
			var implClassName = setting.toString();
			var implClass = classLoaderService.classForName( implClassName );
			try {
				return (Scanner) implClass.getDeclaredConstructor().newInstance();
			}
			catch (Exception e) {
				throw new HibernateException(
						String.format( Locale.ROOT,
								"Unable to instantiate Scanner `%s`",

View on GitHub (pinned to fad1729dce)

Solutions

1. Add a public no-arg constructor to the Scanner implementation.
2. Register an instance instead of the Class: the 'setting instanceof Scanner' branch accepts it without reflection.
3. 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.
4. Prefer PersistenceSettings.SCANNING with a ScanningProvider per its apiNote, which is the supported extension point.

Example fix

// before
settings.put( PersistenceSettings.SCANNER, ArchiveScanner.class ); // only ctor: ArchiveScanner(Path)

// after
public ArchiveScanner() { this(Paths.get(System.getProperty("archive.root"))); }
// or pass an instance
settings.put( PersistenceSettings.SCANNER, new ArchiveScanner(archiveRoot) );

Class<?> impl = ArchiveScanner.class;
assert org.hibernate.boot.scan.spi.Scanner.class.isAssignableFrom( impl ) : "not a Scanner";
try { impl.getDeclaredConstructor(); }
catch ( NoSuchMethodException e ) { throw new IllegalStateException( "Scanner needs a no-arg constructor", e ); }

static boolean safeScannerSetting(Object setting) {
    return setting instanceof org.hibernate.boot.scan.spi.Scanner // instance
            || ( setting instanceof Class<?> c
                 && org.hibernate.boot.scan.spi.Scanner.class.isAssignableFrom( c ) );
}

try { MetadataSources sources = new MetadataSources( ssr ); }
catch ( HibernateException e ) {
    if ( e.getMessage() != null && e.getMessage().startsWith( "Unable to instantiate Scanner" ) ) {
        // inspect cause: constructor missing vs constructor threw vs wrong type
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to instantiate ScanningProvider `%s`
• Unable to instantiate configured ArchiveDescriptorFactory -
• Unable to instantiate specified event listener class:
• Could not instantiate event listener '{}'
• Unable to instantiate StatementObserver - {}

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/10f9784414eb895b. Report an issue: GitHub.