hibernate/hibernate-orm · error · ConfigurationException

<mapping/> named unexpected reference type

Error message

<mapping/> named unexpected reference type

What it means

Every <mapping .../> entry in hibernate.cfg.xml must name exactly one mapping source through one of the attributes class, file, resource, jar, or package. MappingReference.from(JaxbCfgMappingType) checks these attributes in order and throws ConfigurationException '<mapping/> named unexpected reference type' when all of them are empty, i.e. the element names nothing at all.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/cfgxml/spi/MappingReference.java:61

	public static MappingReference consume(JaxbCfgMappingReferenceType jaxbMapping) {
		if ( StringHelper.isNotEmpty( jaxbMapping.getClazz() ) ) {
			return new MappingReference( Type.CLASS, jaxbMapping.getClazz() );
		}
		else if ( StringHelper.isNotEmpty( jaxbMapping.getFile() ) ) {
			return  new MappingReference( Type.FILE, jaxbMapping.getFile() );
		}
		else if ( StringHelper.isNotEmpty( jaxbMapping.getResource() ) ) {
			return new MappingReference( Type.RESOURCE, jaxbMapping.getResource() );
		}
		else if ( StringHelper.isNotEmpty( jaxbMapping.getJar() ) ) {
			return new MappingReference( Type.JAR, jaxbMapping.getJar() );
		}
		else if ( StringHelper.isNotEmpty( jaxbMapping.getPackage() ) ) {
			return new MappingReference( Type.PACKAGE, jaxbMapping.getPackage() );
		}
		else {
			throw new ConfigurationException( "<mapping/> named unexpected reference type" );
		}
	}

	public void apply(MetadataSources metadataSources) {
		switch ( getType() ) {
			case RESOURCE: {
				metadataSources.addResource( getReference() );
				break;
			}
			case CLASS: {
				metadataSources.addAnnotatedClassName( getReference() );
				break;
			}
			case FILE: {
				metadataSources.addFile( getReference() );
				break;
			}
			case PACKAGE: {

View on GitHub (pinned to fad1729dce)

Solutions

1. Add exactly one non-empty attribute to the <mapping/> element, e.g. <mapping class="com.acme.User"/> or <mapping resource="com/acme/User.hbm.xml"/>
2. Delete the empty <mapping/> element if no mapping was intended
3. If the file is generated or filtered, fix the template and build so attribute values never render empty

Example fix

<!-- before -->
<mapping/>

<!-- after -->
<mapping class="com.acme.User"/>

// Pre-validate every <mapping/> element before bootstrap
Document cfg = DocumentBuilderFactory.newInstance().newDocumentBuilder()
        .parse(new File("hibernate.cfg.xml"));
NodeList mappings = cfg.getElementsByTagName("mapping");
for (int i = 0; i < mappings.getLength(); i++) {
    NamedNodeMap attrs = mappings.item(i).getAttributes();
    boolean named = Stream.of("resource", "class", "file", "jar", "package")
            .anyMatch(a -> attrs.getNamedItem(a) != null
                    && !attrs.getNamedItem(a).getTextContent().isBlank());
    if (!named) throw new IllegalStateException("<mapping/> without a reference attribute at index " + i);
}

try {
    new Configuration().configure(cfgXml);
}
catch (ConfigurationException e) {
    if (e.getMessage().contains("unexpected reference type")) {
        // find the bare <mapping/> element and add exactly one attribute
    }
    throw e;
}

When it happens

Trigger: A bare <mapping/> element (no class/resource/file/jar/package attribute) in hibernate.cfg.xml, or attributes present but with empty-string values, so StringHelper.isNotEmpty fails for every candidate in MappingReference.java:55-60.

Common situations: Commenting out an attribute but leaving the element; generated or Maven-filterated cfg.xml where the placeholder substitution produced an empty value; copy-paste of a mapping element with the attribute forgotten.

Related errors

• The specified class cannot be null
• Invalid access type " + propertyAccessType + " for property
• The INSERT statement for table [%s] contains no column, and
• The {storageEngine} storage engine is not supported
• cannot recreate collection while filter is enabled: " + coll

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