hibernate/hibernate-orm · error · HibernateException

Unable to instantiate ScanningProvider `%s`

Error message

Unable to instantiate ScanningProvider `%s`

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/jpa/boot/spi/PersistenceConfigurationDescriptor.java:317

	private static ScanningProvider determineScanningProviderFromSetting(
			@Nonnull ConfigurationService configurationService,
			@Nonnull ClassLoaderService classLoaderService) {
		var providerSetting = configurationService.getSettings().get( PersistenceSettings.SCANNING );
		if ( providerSetting == null ) {
			return null;
		}

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

View on GitHub (pinned to fad1729dce)

Solutions

1. Add a public no-arg constructor to your ScanningProvider implementation.
2. Keep the provider stateless at construction; defer any resource acquisition to the scan call.
3. Verify the class implements org.hibernate.jpa.boot.spi.ScanningProvider and is concrete.
4. Check the wrapped cause - if the constructor itself threw, fix that initialization code.

Example fix

// before
public class FastClasspathScanner implements ScanningProvider {
    public FastClasspathScanner(Index index) { ... } // only arg ctor
}

// after
public class FastClasspathScanner implements ScanningProvider {
    public FastClasspathScanner() { }
    public FastClasspathScanner(Index index) { ... }
}

Class<?> c = (Class<?>) settings.get("hibernate.archive.scanning");
if (c != null) c.getDeclaredConstructor().newInstance(); // assert no-arg ctor exists before boot

When it happens

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

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

Related errors

• Unable to instantiate Scanner `%s`
• The {} class [{}] could not be instantiated
• Unable to instantiate configured ArchiveDescriptorFactory -
• Duplicate generator name '%s'; you will likely want to set t
• Duplicate generator name %s; you will likely want to set the

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