hibernate/hibernate-orm · error · HibernateException

Unable to instantiate configured ArchiveDescriptorFactory -

Error message

Unable to instantiate configured ArchiveDescriptorFactory - {}

What it means

Thrown by PersistenceConfigurationDescriptor.determineArchiveDescriptorFactory() as a HibernateException when the class configured via hibernate.archive.interpreter (Class-object form) cannot be instantiated. ArchiveDescriptorFactory decides how archive URLs (jars, directories, nested archives) are interpreted during scanning; a custom implementation must be constructible with a public no-arg constructor.

Source

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

						e
				);
			}
		}
	}

	private static ArchiveDescriptorFactory determineArchiveDescriptorFactory(
			@Nonnull ConfigurationService configurationService,
			@Nonnull ClassLoaderService classLoaderService) {
		final Object setting = configurationService.getSettings().get( PersistenceSettings.SCANNER_ARCHIVE_INTERPRETER );
		if ( setting instanceof ArchiveDescriptorFactory ref ) {
			return ref;
		}
		else if ( setting instanceof Class<?> implClass ) {
			try {
				return (ArchiveDescriptorFactory) implClass.getDeclaredConstructor().newInstance();
			}
			catch (Exception e) {
				throw new HibernateException( "Unable to instantiate configured ArchiveDescriptorFactory - " + implClass.getName(), e );
			}
		}
		else if ( setting != null ) {
			var implClassName = setting.toString();
			var implClass = classLoaderService.classForName( implClassName );
			try {
				return (ArchiveDescriptorFactory) implClass.getDeclaredConstructor().newInstance();
			}
			catch (Exception e) {
				throw new HibernateException( "Unable to instantiate configured ArchiveDescriptorFactory - " + implClass.getName(), e );
			}
		}
		return new StandardArchiveDescriptorFactory();
	}

}

View on GitHub (pinned to fad1729dce)

Solutions

Give the ArchiveDescriptorFactory implementation a public no-arg constructor.
Ensure the class is public, concrete, and implements org.hibernate.boot.archive.scan.spi.ArchiveDescriptorFactory.
Check the cause for a constructor-thrown exception and defer any I/O setup to first use.
If you only need a different jar protocol handler, consider contributing via ServiceLoader instead of this setting.

Example fix

// before
public class VfsArchiveDescriptorFactory implements ArchiveDescriptorFactory {
    VfsArchiveDescriptorFactory(Vfs vfs) { ... } // package-private + args
}

// after
public class VfsArchiveDescriptorFactory implements ArchiveDescriptorFactory {
    public VfsArchiveDescriptorFactory() { }
    public void setVfs(Vfs vfs) { ... }
}

Defensive patterns

Strategy: validation

Validate before calling

Class<?> c = (Class<?>) settings.get("hibernate.archive.interpreter");
if (c != null) c.getDeclaredConstructor().newInstance(); // public no-arg ctor required

Prevention

Make custom ArchiveDescriptorFactory implementations public with public no-arg constructors.
Defer VFS/resource acquisition out of the constructor.

When it happens

Trigger: Setting hibernate.archive.interpreter to a Class whose getDeclaredConstructor().newInstance() fails - missing no-arg constructor, abstract class, non-public class/constructor, or a throwing constructor - during EntityManagerFactory boot.

Common situations: Custom archive interpretation for exotic packaging (e.g. WAR/EAR layouts or virtual filesystems) where the implementation class was written with constructor parameters or package-private visibility.

Related errors

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