hibernate/hibernate-orm · error · HibernateException

Entity does not define a natural id : ${entityName}

Error message

Entity does not define a natural id : ${entityName}

What it means

Error "Entity does not define a natural id : ${entityName}" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/persister/entity/AbstractEntityPersister.java:5176

	@Override
	public boolean hasSubselectLoadableCollections() {
		return hasSubselectLoadableCollections;
	}

	@Override
	public boolean hasSubselectLoadableAttributes() {
		return hasSubselectLoadableAttributes;
	}

	@Override
	public boolean hasCollectionNotReferencingPK() {
		return hasCollectionNotReferencingPK;
	}

	protected void verifyHasNaturalId() {
		if ( ! hasNaturalIdentifier() ) {
			throw new HibernateException( "Entity does not define a natural id : " + getEntityName() );
		}
	}

	@Override
	public Object getNaturalIdentifierSnapshot(Object id, SharedSessionContractImplementor session) {
		verifyHasNaturalId();
		if ( CORE_LOGGER.isTraceEnabled() ) {
			CORE_LOGGER.gettingCurrentNaturalIdSnapshot( getEntityName(), id );
		}
		return getNaturalIdLoader().resolveIdToNaturalId( id, session );
	}


	@Override
	public NaturalIdLoader<?> getNaturalIdLoader() {
		verifyHasNaturalId();
		if ( naturalIdLoader == null ) {
			naturalIdLoader = naturalIdMapping.makeLoader( this );

View on GitHub (pinned to fad1729dce)

Solutions

1. Annotate attributes with @NaturalId on the entity before using natural-id APIs, or use identifier-based loading instead.

When it happens

Trigger: Thrown when a natural-id based load is attempted on an entity that declares no natural id.

Common situations: See trigger scenarios.

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