{"record":{"id":"99d7af85f17a4b80","repo":"hibernate/hibernate-orm","slug":"mapping-named-unexpected-reference-type","errorCode":null,"errorMessage":"<mapping/> named unexpected reference type","messagePattern":"<mapping/> named unexpected reference type","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/cfgxml/spi/MappingReference.java","lineNumber":61,"sourceCode":"\n\tpublic static MappingReference consume(JaxbCfgMappingReferenceType jaxbMapping) {\n\t\tif ( StringHelper.isNotEmpty( jaxbMapping.getClazz() ) ) {\n\t\t\treturn new MappingReference( Type.CLASS, jaxbMapping.getClazz() );\n\t\t}\n\t\telse if ( StringHelper.isNotEmpty( jaxbMapping.getFile() ) ) {\n\t\t\treturn  new MappingReference( Type.FILE, jaxbMapping.getFile() );\n\t\t}\n\t\telse if ( StringHelper.isNotEmpty( jaxbMapping.getResource() ) ) {\n\t\t\treturn new MappingReference( Type.RESOURCE, jaxbMapping.getResource() );\n\t\t}\n\t\telse if ( StringHelper.isNotEmpty( jaxbMapping.getJar() ) ) {\n\t\t\treturn new MappingReference( Type.JAR, jaxbMapping.getJar() );\n\t\t}\n\t\telse if ( StringHelper.isNotEmpty( jaxbMapping.getPackage() ) ) {\n\t\t\treturn new MappingReference( Type.PACKAGE, jaxbMapping.getPackage() );\n\t\t}\n\t\telse {\n\t\t\tthrow new ConfigurationException( \"<mapping/> named unexpected reference type\" );\n\t\t}\n\t}\n\n\tpublic void apply(MetadataSources metadataSources) {\n\t\tswitch ( getType() ) {\n\t\t\tcase RESOURCE: {\n\t\t\t\tmetadataSources.addResource( getReference() );\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase CLASS: {\n\t\t\t\tmetadataSources.addAnnotatedClassName( getReference() );\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase FILE: {\n\t\t\t\tmetadataSources.addFile( getReference() );\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase PACKAGE: {","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/cfgxml/spi/MappingReference.java#L43-L79","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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\"/>","Delete the empty <mapping/> element if no mapping was intended","If the file is generated or filtered, fix the template and build so attribute values never render empty"],"exampleFix":"<!-- before -->\n<mapping/>\n\n<!-- after -->\n<mapping class=\"com.acme.User\"/>","handlingStrategy":"validation","validationCode":"// Pre-validate every <mapping/> element before bootstrap\nDocument cfg = DocumentBuilderFactory.newInstance().newDocumentBuilder()\n        .parse(new File(\"hibernate.cfg.xml\"));\nNodeList mappings = cfg.getElementsByTagName(\"mapping\");\nfor (int i = 0; i < mappings.getLength(); i++) {\n    NamedNodeMap attrs = mappings.item(i).getAttributes();\n    boolean named = Stream.of(\"resource\", \"class\", \"file\", \"jar\", \"package\")\n            .anyMatch(a -> attrs.getNamedItem(a) != null\n                    && !attrs.getNamedItem(a).getTextContent().isBlank());\n    if (!named) throw new IllegalStateException(\"<mapping/> without a reference attribute at index \" + i);\n}","typeGuard":null,"tryCatchPattern":"try {\n    new Configuration().configure(cfgXml);\n}\ncatch (ConfigurationException e) {\n    if (e.getMessage().contains(\"unexpected reference type\")) {\n        // find the bare <mapping/> element and add exactly one attribute\n    }\n    throw e;\n}","preventionTips":["Never comment out just the attribute of a <mapping/> element - remove the element","If cfg.xml is generated or Maven-filtered, assert non-empty substitution results in CI"],"tags":["hibernate","cfg-xml","mapping","configuration"],"backgroundTag":"missing-configuration-attribute","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}