hibernate/hibernate-orm · error · HibernateException

Entity %s does not specify a natural id

Error message

Entity %s does not specify a natural id

What it means

Error "Entity %s does not specify a natural id" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/metamodel/mapping/EntityMappingType.java:383

	EntityVersionMapping getVersionMapping();

	/**
	 * The type of optimistic locking, if any, defined for this entity mapping
	 */
	default OptimisticLockStyle optimisticLockStyle() {
		return OptimisticLockStyle.NONE;
	}

	/**
	 * The mapping for the natural-id of the entity, if one is defined
	 */
	@Nullable NaturalIdMapping getNaturalIdMapping();

	@Nonnull
	default NaturalIdMapping requireNaturalIdMapping() {
		final var mapping = getNaturalIdMapping();
		if ( mapping == null ) {
			throw new HibernateException( format( "Entity %s does not specify a natural id", getEntityName() ) );
		}
		return mapping;
	}

	/**
	 * The mapping for the row-id of the entity, if one is defined.
	 */
	EntityRowIdMapping getRowIdMapping();

	/**
	 * Mapping for soft-delete support, or {@code null} if soft-delete not defined
	 */
	@Incubating
	default SoftDeleteMapping getSoftDeleteMapping() {
		return null;
	}

	/**

View on GitHub (pinned to fad1729dce)

Solutions

1. Annotate one or more attributes of the entity with @NaturalId before using natural-id loading APIs.
2. Use the regular identifier lookup (find/byId) instead of natural-id access for entities without a natural id.

When it happens

Trigger: Thrown when a natural-id load or lookup is attempted against an entity that declares no @NaturalId attributes.

Common situations: See trigger scenarios.

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