hibernate/hibernate-orm · error · ModelsException

Persistence unit lifecycle callback method not found: %s (%s

Error message

Persistence unit lifecycle callback method not found: %s (%s)

What it means

Error "Persistence unit lifecycle callback method not found: %s (%s)" thrown in hibernate/hibernate-orm.

Source

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

			@Nonnull PersistenceUnitCallbackType callbackType,
			@Nonnull List<CallbackMethod> callbackMethods) {
		if ( lifecycleCallback != null ) {
			MethodDetails namedMethod = null;
			for ( var methodDetails : listenerClassDetails.getMethods() ) {
				if ( methodDetails.getName().equals( lifecycleCallback.getMethodName() ) ) {
					namedMethod = methodDetails;
					if ( hasValidSignature( methodDetails ) ) {
						checkDuplicate( listenerClassDetails, methodDetails, callbackType, callbackMethods );
						callbackMethods.add( new CallbackMethod( callbackType, methodDetails ) );
						return;
					}
				}
			}

			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'");
		}
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Ensure the named callback method exists on the listener class with the required signature (void return, correct single parameter, accessible).

Example fix

Ensure the named callback method exists on the listener class with the required signature (void return, correct single parameter, accessible).

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/285146dae05d5ae5. Report an issue: GitHub.