hibernate/hibernate-orm · error · ModelsException

You can only annotate one callback method per callback type

Error message

You can only annotate one callback method per callback type and parameter type in callback class: %s

What it means

Error "You can only annotate one callback method per callback type and parameter type in callback class: %s" thrown in hibernate/hibernate-orm.

Source

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

			&& 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;
	}

	private static void checkDuplicate(
			@Nonnull ClassDetails listenerClassDetails,
			@Nonnull MethodDetails methodDetails,
			@Nonnull PersistenceUnitCallbackType callbackType,
			@Nonnull List<CallbackMethod> callbackMethods) {
		for ( var callbackMethod : callbackMethods ) {
			if ( callbackMethod.callbackType == callbackType
					&& hasSameParameterType( callbackMethod.methodDetails, methodDetails ) ) {
				throw new ModelsException( "You can only annotate one callback method per callback type and parameter type"
						+ " in callback class: " + listenerClassDetails.getClassName() );
			}
		}
	}

	private static boolean hasSameParameterType(@Nonnull MethodDetails first, @Nonnull MethodDetails second) {
		return first.getArgumentTypes().get( 0 ).toJavaClass()
				.equals( second.getArgumentTypes().get( 0 ).toJavaClass() );
	}

	public record CallbackMethod(
			PersistenceUnitCallbackType callbackType,
			MethodDetails methodDetails) {
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Keep a single callback method per lifecycle event type (and parameter type) in the listener/callback class; merge the logic of the duplicates.

Example fix

Keep a single callback method per lifecycle event type (and parameter type) in the listener/callback class; merge the logic of the duplicates.

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/737318a41242e730. Report an issue: GitHub.