hibernate/hibernate-orm · error · MappingException

An association from the table '" + getTable().getName() + "'

Error message

An association from the table '" + getTable().getName() + "' refers to an unmapped class '" + referencedEntityName + "'

What it means

ForeignKey#resolveReferencedClass looks up the referenced entity by name in the built metadata and throws when no entity binding exists under that exact name. The FK therefore points at a class that is not part of the persistence unit's mapping set.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/ForeignKey.java:198

					+ " ref-columns:" + '(' + getReferencedColumns() + ") as " + getName() + ")";
		}
		else {
			return super.toString();
		}

	}

	@Internal
	public PersistentClass resolveReferencedClass(Metadata metadata) {
		final String referencedEntityName = getReferencedEntityName();
		if ( referencedEntityName == null ) {
			throw new MappingException( "An association from the table '" + getTable().getName() +
					"' does not specify the referenced entity" );
		}

		final var referencedEntity = metadata.getEntityBinding( referencedEntityName );
		if ( referencedEntity == null ) {
			throw new MappingException( "An association from the table '" + getTable().getName() +
					"' refers to an unmapped class '" + referencedEntityName + "'" );
		}

		return referencedEntity;
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Make the referenced name exactly match the mapped entity: the @Entity(name=...) value, the hbm entity-name attribute, or the fully-qualified class name when no explicit name is set.
Ensure the target class has @Entity and is included via component scanning, persistence.xml <class>, or MetadataSources.
If the name is correct, verify the entity's artifact is actually part of the persistence unit.

Example fix

// before - entity declared with an explicit name
@Entity(name = "ItemMaster")
public class Item { ... }
// mapping references "Item"

// after - align the reference (or drop the explicit name)
@Entity
public class Item { ... }

Defensive patterns

Strategy: try-catch

Try / catch

try {
    metadata = sources.buildMetadata();
} catch (MappingException e) {
    // 'refers to an unmapped class <name>' - compare <name> against the
    // scanned entity set (@Entity names / entity-name attributes)
    throw e;
}

Prevention

Avoid @Entity(name=...) unless required; default names keep references stable.
Assert in a test that every entity name referenced by mappings exists in the scanned entity set.
Keep persistence.xml or the annotated-classes list in sync when moving entities between modules.

When it happens

Trigger: Referencing an @Entity(name="X") custom name with the plain class name or vice versa; the target class lacks @Entity or is missing from persistence.xml / the annotated-classes list; an entity-name string in hbm has a typo; the entity jar is not included in the persistence unit.

Common situations: Introducing explicit @Entity names during cleanup; splitting the domain into modules and forgetting to register some entities; dynamic hbm mappings assembled from files; differing entity-name conventions across teams.

Related errors

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