hibernate/hibernate-orm · error · AuditException

Entity change tracking is not enabled. Use a @Changelog with

Error message

Entity change tracking is not enabled. Use a @Changelog with a @Changelog.ModifiedEntities property (e.g. DefaultTrackingModifiedEntitiesChangelog).

What it means

Cross-changeset queries on AuditLog - getEntityTypesModifiedAt, findAllEntitiesModifiedAt, findAllEntitiesGroupedByModificationType - read the list of changed entity names from the @Changelog.ModifiedEntities property of the changelog entity. When the configured changelog has no such property, requireEntityChangeTracking() throws AuditException explaining how to enable tracking.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/audit/internal/AuditLogImpl.java:328

		for ( String entityName : queryRevChangesEntityNames( changesetId ) ) {
			doFindEntitiesGroupedByModificationType( entityName, changesetId, Object.class )
					.forEach( (mt, entities) -> result.get( mt ).addAll( entities ) );
		}
		return result;
	}

	private List<String> queryRevChangesEntityNames(Object changesetId) {
		return auditSession.createSelectionQuery(
				"select element(r." + modifiedEntitiesProperty + ")"
						+ " from " + changelogName + " r"
						+ " where r." + changesetIdProperty + " = :csId",
				String.class
		).setParameter( "csId", changesetId ).getResultList();
	}

	private void requireEntityChangeTracking() {
		if ( modifiedEntitiesProperty == null ) {
			throw new AuditException(
					"Entity change tracking is not enabled. "
							+ "Use a @Changelog with a @Changelog.ModifiedEntities property "
							+ "(e.g. DefaultTrackingModifiedEntitiesChangelog)."
			);
		}
	}

	// --- Changeset entity queries ---

	@Override
	public Instant getChangesetTimestamp(Object changesetId) {
		requireNonNull( changesetId, "Changeset identifier" );
		requireChangelog();
		final String hql = "select e." + timestampProperty
				+ " from " + changelogName + " e"
				+ " where e." + changesetIdProperty + " = :rev";
		final var result = auditSession
				.createSelectionQuery( hql, Object.class )

View on GitHub (pinned to fad1729dce)

Solutions

1. Extend DefaultTrackingModifiedEntitiesChangelog, or add a @Changelog.ModifiedEntities property to your changelog entity, then update the schema.
2. If entity-change tracking is not needed, replace these calls with per-entity queries (getChangesets / find at changeset) that do not require the property.

Example fix

// before
@Changelog
public class RevEntity {
    @Changelog.ChangesetId @GeneratedValue Long id;
    @Changelog.Timestamp Instant at;
}
// after - changelog that tracks modified entity names
@Changelog
public class RevEntity extends DefaultTrackingModifiedEntitiesChangelog { ... }

// feature check before calling modified-entity APIs
boolean trackingEnabled = /* changelog entity declares a @Changelog.ModifiedEntities property */
    Arrays.stream(RevEntity.class.getDeclaredFields())
        .anyMatch(f -> f.isAnnotationPresent(Changelog.ModifiedEntities.class));
if (!trackingEnabled) throw new UnsupportedOperationException("enable modified-entity tracking first");

try {
    types = auditLog.getEntityTypesModifiedAt(csId);
}
catch (AuditException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Entity change tracking is not enabled")) {
        // fall back to per-entity queries that need no changelog tracking
    }
    else throw e;
}

When it happens

Trigger: Calling any AuditLog.findAllEntitiesModifiedAt / getEntityTypesModifiedAt / findAllEntitiesGroupedByModificationType variant while the registered changelog entity only has changeset-id and timestamp properties.

Common situations: Starting with a minimal changelog for at-changeset queries, then later calling modified-entity queries; porting Envers getCrossTypeRevisionChangesReader code that required ModifiedEntityNamesConfig.

Related errors

• No @Changelog configured. This operation requires a changelo
• Audit graph mutation plan used with non-graph action queue
• Audit graph mutation plan used with non-graph action queue
• Cannot convert changeset timestamp to Instant: <value>
• @Changelog.ChangesetId property '<changesetIdProperty>' is n

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