hibernate/hibernate-orm · error · ModelsException

Callback method '%s' annotated '@%s' in '%s' must return voi

Error message

Callback method '%s' annotated '@%s' in '%s' must return void and have one parameter of type 'EntityAgent', 'EntityManager', or 'EntityManagerFactory'

What it means

Error "Callback method '%s' annotated '@%s' in '%s' must return void and have one parameter of type 'EntityAgent', 'EntityManager', or 'EntityManagerFactory'" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/models/spi/PersistenceUnitLifecycleEventHandler.java:157

					}
				}
			}

			if ( namedMethod != null ) {
				validateSignature( listenerClassDetails, namedMethod, callbackAnnotation );
			}
			throw new ModelsException( "Persistence unit lifecycle callback method not found: "
										+ lifecycleCallback.getMethodName()
										+ " (" + listenerClassDetails.getClassName() + ")" );
		}
	}

	private static void validateSignature(
			@Nonnull ClassDetails listenerClassDetails,
			@Nonnull MethodDetails methodDetails,
			@Nonnull Class<? extends Annotation> callbackAnnotation) {
		if ( !hasValidSignature( methodDetails ) ) {
			throw new ModelsException( "Callback method '"
					+ methodDetails.getName() + "' annotated '@"
					+ callbackAnnotation.getSimpleName() + "' in '"
					+ listenerClassDetails.getClassName()
					+ "' must return void and have one parameter of type 'EntityAgent', 'EntityManager', or 'EntityManagerFactory'");
		}
	}

	private static boolean hasValidSignature(@Nonnull MethodDetails methodDetails) {
		return methodDetails.getArgumentTypes().size() == 1
			&& methodDetails.getReturnType() == ClassDetails.VOID_CLASS_DETAILS
			&& isPersistenceUnitLifecycleTarget( methodDetails.getArgumentTypes().get( 0 ) );
	}

	private static boolean isPersistenceUnitLifecycleTarget(@Nonnull ClassDetails argumentType) {
		final Class<?> javaClass = argumentType.toJavaClass();
		return javaClass == EntityManagerFactory.class
			|| javaClass == EntityManager.class
			|| javaClass == EntityAgent.class;

View on GitHub (pinned to fad1729dce)

Solutions

1. Change the persistence-unit lifecycle callback to accept exactly one parameter of type EntityAgent, EntityManager, or EntityManagerFactory and return void.

Example fix

Change the persistence-unit lifecycle callback to accept exactly one parameter of type EntityAgent, EntityManager, or EntityManagerFactory and return void.

When it happens

Trigger: A JPA entity-listener or lifecycle callback violates the callback contract.

Common situations: Listener classes with missing lifecycle annotations, wrong method signatures, or multiple methods for the same event type.

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