hibernate/hibernate-orm · error · MappingException

Attribute types for a dynamicEntity must be explicitly speci

Error message

Attribute types for a dynamicEntity must be explicitly specified: " + propertyName

What it means

Thrown by SimpleValue.setTypeUsingReflection when Hibernate must determine a property type by reflecting on a class, but className is null — which is always the case for dynamic-map (entity-name based) entities, since they have no Java class to reflect on. Dynamic entities exist only as Maps of names to values, so every property must declare its type explicitly in the mapping. Without a type attribute there is no way for Hibernate to know what to store in the map slot.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java:643

		this.attributeConverterDescriptor = descriptor;
	}

	protected ConverterDescriptor<?,?> getAttributeConverterDescriptor() {
		return attributeConverterDescriptor;
	}

	@Override
	public void setTypeUsingReflection(String className, String propertyName) throws MappingException {
		// NOTE: this is called as the last piece in setting SimpleValue type information,
		//       and implementations rely on that fact, using it as a signal that all
		//       the information it is going to get is already specified at this point
		if ( typeName == null && type == null ) {
			if ( attributeConverterDescriptor == null ) {
				// This is here to work like legacy. This should change when we integrate with metamodel
				// to look for JdbcType and JavaType individually and create the BasicType (well, really
				// keep a registry of [JdbcType,JavaType] -> BasicType...)
				if ( className == null ) {
					throw new MappingException(
							"Attribute types for a dynamic entity must be explicitly specified: " + propertyName );
				}
				typeName = getClass( className, propertyName ).getName();
				// TODO: To fully support isNationalized here we need to do the process hinted at above
				// 		 essentially, much of the logic from #buildAttributeConverterTypeAdapter wrt
				// 		 resolving a (1) JdbcType, a (2) JavaType and dynamically building a BasicType
				// 		 combining them.
			}
			else {
				// we had an AttributeConverter
				type = buildAttributeConverterTypeAdapter();
			}
		}
		// otherwise assume either
		// (a) explicit type was specified or
		// (b) determine was already performed
	}

View on GitHub (pinned to fad1729dce)

Solutions

  1. Add an explicit type attribute to every untyped property of the dynamic entity, e.g. <property name="amount" type="big_decimal"/> or type="org.example.MyType".
  2. For association properties, supply the entity class: <many-to-one name="customer" class="Customer"/>.
  3. If reflection-based type discovery is desired, map the entity as a normal POJO class instead of entity-name/dynamic-map.
  4. Run Metadata building early (e.g. a startup test that builds SessionFactory) so this surfaces at deploy time, not first use.

Example fix

<!-- before -->
<hibernate-mapping>
  <class entity-name="Item">
    <id name="id" type="long"/>
    <property name="price"/>  <!-- missing type -->
  </class>
</hibernate-mapping>

<!-- after -->
<hibernate-mapping>
  <class entity-name="Item">
    <id name="id" type="long"/>
    <property name="price" type="big_decimal"/>
  </class>
</hibernate-mapping>
Defensive patterns

Strategy: validation

Validate before calling

// fail fast when bootstrapping dynamic-map mappings: verify every property has a type
Metadata metadata = metadataSources.buildMetadata(); // throws MappingException with the property name if a type is missing

Try / catch

try {
    sessionFactory = cfg.buildSessionFactory();
} catch (MappingException e) {
    if (e.getMessage().startsWith("Attribute types for a dynamic entity")) {
        // message contains the offending property name — log and surface config guidance
        log.error("Dynamic-entity property missing 'type' attribute: {}", e.getMessage());
    }
    throw e;
}

Prevention

When it happens

Trigger: Using hbm.xml <hibernate-mapping> with entity-name="..." (dynamic-map representation) and a <property name="x"/> element that omits the type attribute and has no @Type/@TypeDef equivalent; also a @ManyToOne in a dynamic entity without class/target entity; similarly for <key-property> and other value mappings in dynamic-map mode when no type name was supplied.

Common situations: Legacy Hibernate 2/3-style dynamic-map mappings where a type attribute was accidentally dropped; migrating mappings to dynamic entities and forgetting that reflection cannot backfill types; XML edited by hand or generated by tools that omit type="..."; using SessionFactory.openStatelessSession with entity-name APIs against incompletely typed mappings.

Related errors

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