hibernate/hibernate-orm · error · MappingException

@Changelog '{}' must have a property annotated with @Changel

Error message

@Changelog '{}' must have a property annotated with @Changelog.ChangesetId

What it means

A changelog (changeset) entity declared with Hibernate 7's '@Changelog' must contain exactly one member annotated '@Changelog.ChangesetId' to identify each changeset. AuditHelper scans the class and its supertypes for that marker; if no field carries it, binding throws this MappingException during metadata building.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/AuditHelper.java:464

						classDetails
				);
				revTimestampMember = checkAnnotation(
						member,
						revTimestampMember,
						Changelog.Timestamp.class,
						classDetails
				);
				modifiedEntityNamesMember = checkAnnotation(
						member,
						modifiedEntityNamesMember,
						Changelog.ModifiedEntities.class,
						classDetails
				);
			}
		}

		if ( revNumberMember == null ) {
			throw new MappingException(
					"@Changelog '" + classDetails.getName()
							+ "' must have a property annotated with @Changelog.ChangesetId"
			);
		}
		if ( revTimestampMember == null ) {
			throw new MappingException(
					"@Changelog '" + classDetails.getName()
							+ "' must have a property annotated with @Changelog.Timestamp"
			);
		}

		// Configure the supplier eagerly
		final var serviceRegistry = context.getBootstrapContext().getServiceRegistry();
		final var listenerClass = changelog.listener();
		final var listener = listenerClass != ChangesetListener.class
				? serviceRegistry.requireService( ManagedBeanRegistry.class )
						.getBean( listenerClass ).getBeanInstance()
				: null;

View on GitHub (pinned to fad1729dce)

Solutions

Add a field annotated '@Changelog.ChangesetId' to the @Changelog entity — typically the primary key of each changeset row (e.g. Long id with a generator).
Make sure the annotation is the exact nested type '@Changelog.ChangesetId' on a FIELD of the entity or one of its mapped supertypes.
Ensure exactly one such member: also add the required '@Changelog.Timestamp' member (checked next).

Example fix

// before
@Changelog
@Entity
public class Changeset {
    @Id @GeneratedValue Long id; // not a @ChangesetId
    @Changelog.Timestamp Instant at;
}

// after
@Changelog
@Entity
public class Changeset {
    @Id @GeneratedValue
    @Changelog.ChangesetId
    Long id;

    @Changelog.Timestamp
    Instant at;
}

Defensive patterns

Strategy: validation

Validate before calling

// Guard: @Changelog entity must have a @Changelog.ChangesetId field
boolean hasId = Arrays.stream(cls.getDeclaredFields())
    .anyMatch(f -> f.isAnnotationPresent(Changelog.ChangesetId.class));
if (cls.isAnnotationPresent(Changelog.class) && !hasId) {
    throw new IllegalStateException(cls.getName()
        + ": missing @Changelog.ChangesetId member");
}

Try / catch

try {
    factory = cfg.buildSessionFactory();
} catch (MappingException e) {
    // 'must have a property annotated with @Changelog.ChangesetId' -> add it
    throw newConfigurationException("Incomplete changelog entity", e);
}

Prevention

Start changelog entities from a reviewed template containing ChangesetId + Timestamp members.
Write one bootstrap test that instantiates the audit configuration; it catches all three @Changelog errors.

When it happens

Trigger: An '@Changelog @Entity' class with @Changelog.Timestamp and/or @Changelog.ModifiedEntities fields but NO field annotated '@Changelog.ChangesetId'; annotating a method instead of a field; misspelling the nested annotation so the scan misses it.

Common situations: Building the changeset entity from the docs and skipping the id member; renaming/refactoring that dropped the annotation; hand-porting an Envers @RevisionEntity where the id used @Id + @GeneratedValue instead of the changelog marker.

Related errors

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