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 take one argument

What it means

Error "Callback method '%s' annotated '@%s' in '%s' must return void and take one argument" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/models/spi/LifecycleEventHandler.java:590

					listenerClassDetails,
					callbackAnnotation,
					callbackType,
					methodDetails,
					callbackMethods
			);
		}
	}

	private static void applyTargetedAnnotatedCallback(
			ClassDetails listenerClassDetails,
			ClassDetails targetClassDetails,
			MethodDetails methodDetails,
			Class<? extends Annotation> callbackAnnotation,
			CallbackType callbackType,
			List<LifecycleEventHandler> descriptors) {
		if ( methodDetails.hasDirectAnnotationUsage( callbackAnnotation ) ) {
			if ( !matchesSignature( JpaEventListenerStyle.LISTENER, methodDetails ) ) {
				throw new ModelsException( "Callback method '"
						+ methodDetails.getName() + "' annotated '@"
						+ callbackAnnotation.getSimpleName() + "' in '"
						+ listenerClassDetails.getClassName() + "'"
						+ signatureRequirement( JpaEventListenerStyle.LISTENER ) );
			}
			if ( firstParameterType( methodDetails )
					.isAssignableFrom( targetClassDetails.toJavaClass() ) ) {
				addIfAbsent( listenerClassDetails, callbackType, methodDetails, descriptors );
			}
		}
	}

	private static void addIfAbsent(
			ClassDetails listenerClassDetails,
			CallbackType callbackType,
			MethodDetails methodDetails,
			List<LifecycleEventHandler> descriptors) {
		for ( var existing : descriptors ) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Change the callback method signature to void with exactly one parameter (the entity for entity callbacks, or the allowed context type).

Example fix

Change the callback method signature to void with exactly one parameter (the entity for entity callbacks, or the allowed context type).

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