hibernate/hibernate-orm · error · HibernateException

Unable to instantiate configured ArchiveDescriptorFactory -

Error message

Unable to instantiate configured ArchiveDescriptorFactory - {}

What it means

Hibernate resolves the configured ArchiveDescriptorFactory (PersistenceSettings.SCANNER_ARCHIVE_INTERPRETER, 'hibernate.archive.interpreter') that interprets archive URLs during scanning. When the setting is a Class, determineArchiveDescriptorFactory reflectively instantiates it via getDeclaredConstructor().newInstance(); failure (no accessible no-arg constructor, abstract class, throwing constructor, or non-ArchiveDescriptorFactory type causing a ClassCastException) raises this HibernateException with the cause attached.

Source

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

						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();
	}

	private ScanningHelper() {
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Add a public no-arg constructor to the ArchiveDescriptorFactory implementation.
Pass an instance instead of a Class - the 'setting instanceof ArchiveDescriptorFactory' branch uses it directly.
Check the cause: ClassCastException usually means you supplied an ArchiveDescriptor implementation class rather than an ArchiveDescriptorFactory.
If you do not need custom archive interpretation, remove the setting entirely - the code falls back to new StandardArchiveDescriptorFactory().

Example fix

// before
settings.put( PersistenceSettings.SCANNER_ARCHIVE_INTERPRETER, NestedJarDescriptor.class );
// NestedJarDescriptor is an ArchiveDescriptor (wrong type) or lacks a no-arg ctor

// after
public NestedJarDescriptorFactory() {}
settings.put( PersistenceSettings.SCANNER_ARCHIVE_INTERPRETER, new NestedJarDescriptorFactory() );
// or simply omit the setting to use StandardArchiveDescriptorFactory

Defensive patterns

Strategy: validation

Validate before calling

Class<?> impl = NestedJarDescriptorFactory.class;
if ( !org.hibernate.boot.archive.scan.spi.ArchiveDescriptorFactory.class.isAssignableFrom( impl ) )
    throw new IllegalArgumentException( "supply an ArchiveDescriptorFactory, not an ArchiveDescriptor" );
impl.getDeclaredConstructor();

Type guard

static boolean safeInterpreterSetting(Object setting) {
    return setting instanceof org.hibernate.boot.archive.scan.spi.ArchiveDescriptorFactory
            || ( setting instanceof Class<?> c
                 && org.hibernate.boot.archive.scan.spi.ArchiveDescriptorFactory.class.isAssignableFrom( c ) );
}

Try / catch

try { ssr = ssrb.build(); }
catch ( HibernateException e ) {
    if ( e.getMessage() != null && e.getMessage().startsWith( "Unable to instantiate configured ArchiveDescriptorFactory" ) ) {
        // cause: ClassCastException = wrong interface; NoSuchMethodException = no no-arg ctor
    }
    throw e;
}

Prevention

Remember the factory-vs-descriptor distinction: hibernate.archive.interpreter takes an ArchiveDescriptorFactory.
Omit the setting when standard archive handling suffices - StandardArchiveDescriptorFactory is the default.
Pass an instance to avoid reflection on constructors.

When it happens

Trigger: Setting 'hibernate.archive.interpreter' to a Class object implementing archive interpretation (e.g. custom jar/ear layout handling) that cannot be reflectively instantiated with a declared no-arg constructor or does not implement ArchiveDescriptorFactory.

Common situations: Custom archive interpreter for exotic packaging (e.g. nested jars in an app-server) whose constructor requires arguments; interpreter failing in its constructor on unavailable resources; providing a Class<ArchiveDescriptor> (the per-archive type) instead of the factory type by mistake.

Related errors

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