hibernate/hibernate-orm · critical · HibernateException

Unable to instantiate custom MutationExecutorService : <clas

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'.

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)

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); }
Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

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

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