hibernate/hibernate-orm · critical · HibernateException

Unable to instantiate custom MutationExecutorService

Error message

Unable to instantiate custom MutationExecutorService : <className>

What it means

MutationExecutorServiceInitiator's generic catch around customImplClass.getConstructor().newInstance(): instantiation failed for a reason other than a missing constructor — class or constructor not public (IllegalAccessException), constructor threw (InvocationTargetException), class is abstract, or another instantiation problem. Boot fails with HibernateException 'Unable to instantiate custom MutationExecutorService'.

Solutions

1. Make the class concrete and public with a public no-arg constructor
2. Move any logic that can fail out of the constructor (lazy-initialize in initiateService/first use instead)
3. Read the InvocationTargetException cause in the stack trace — it carries the real exception your constructor threw
4. Verify the class is visible to Hibernate's ClassLoaderService (same classloader / proper module exports)

Example fix

// before: constructor does boot-time work
public MyExecutor() { this.pool = ServiceLocator.require(Pool.class); }

// after: fail-safe constructor, lazy dependency
public MyExecutor() { }
private Pool pool() { return ServiceLocator.require(Pool.class); }

// instantiate the custom executor in a pre-boot check
try {
    Class.forName(executorClassName).getConstructor().newInstance();
}
catch (ReflectiveOperationException e) {
    throw new IllegalStateException("custom MutationExecutorService not instantiable", e);
}

When it happens

Trigger: hibernate.jdbc.mutation.executor points at an abstract class, a non-public class/constructor, or a constructor whose body throws (e.g. it depends on services not yet available at boot time).

Common situations: Custom executors that read config or touch the service registry inside the constructor; refactoring that made the class abstract with a factory instead; classpath/visibility issues in module (JPMS) or OSGi deployments.

Related errors

• Could not locate appropriate MutationExecutorService…
• Could not instantiate entity
• Could not instantiate entity
• Could not instantiate entity
• Could not instantiate named strategy class

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

Appendix: source

Thrown at hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/MutationExecutorServiceInitiator.java:71

			final Class<? extends MutationExecutorService> customImplClass;
			if ( custom instanceof Class ) {
				//noinspection unchecked
				customImplClass = (Class<? extends MutationExecutorService>) custom;
			}
			else {
				customImplClass = classLoaderService.classForName( custom.toString() );
			}

			try {
				return customImplClass.getConstructor().newInstance();
			}
			catch (NoSuchMethodException e) {
				throw new HibernateException(
						"Could not locate appropriate MutationExecutorService constructor : " + customImplClass.getName(),
						e );
			}
			catch (Exception e) {
				throw new HibernateException(
						"Unable to instantiate custom MutationExecutorService : " + customImplClass.getName(), e );
			}
		}
	}

	private static MutationExecutorService discover(ClassLoaderService classLoaderService) {
		final var discovered = classLoaderService.loadJavaServices( MutationExecutorService.class );
		final var iterator = discovered.iterator();
		if ( iterator.hasNext() ) {
			final var selected = iterator.next();
			if ( iterator.hasNext() ) {
				throw new HibernateException(
						"Multiple MutationExecutorService service registrations found via ServiceLoader; "
						+ "specify one explicitly via '" + EXECUTOR_KEY + "'" );
			}
			return selected;
		}
		else {

View on GitHub (pinned to fad1729dce)