{"record":{"id":"75e033d92dbc3935","repo":"hibernate/hibernate-orm","slug":"could-not-parse-mapping-document-s-s","errorCode":null,"errorMessage":"Could not parse mapping document: %s (%s)","messagePattern":"Could not parse mapping document: (.+?) \\((.+?)\\)","errorType":"exception","errorClass":"InvalidMappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/InputStreamXmlSource.java","lineNumber":60,"sourceCode":"\n\t/**\n\t * Utility form to create a {@linkplain Binding binding} from an input source.\n\t *\n\t * @param stream The stream from which to read the mappings\n\t * @param origin Description of the source from which the stream came\n\t * @param autoClose Whether to {@linkplain InputStream#close() close} the stream after we have processed it\n\t * @param binder The JAXB binder to use\n\t */\n\tpublic static Binding<? extends JaxbBindableMappingDescriptor> fromStream(\n\t\t\tInputStream stream,\n\t\t\tOrigin origin,\n\t\t\tboolean autoClose,\n\t\t\tMappingBinder binder) {\n\t\ttry {\n\t\t\treturn binder.bind( stream, origin );\n\t\t}\n\t\tcatch ( Exception e ) {\n\t\t\tthrow new InvalidMappingException( origin, e );\n\t\t}\n\t\tfinally {\n\t\t\tif ( autoClose ) {\n\t\t\t\ttry {\n\t\t\t\t\tstream.close();\n\t\t\t\t}\n\t\t\t\tcatch ( IOException ioe ) {\n\t\t\t\t\tJAXB_LOGGER.unableToCloseInputStream( ioe );\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n","sourceCodeStart":42,"sourceCodeEnd":74,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/jaxb/internal/InputStreamXmlSource.java#L42-L74","documentation":"InputStreamXmlSource.fromStream wraps any exception thrown while the MappingBinder binds the stream into InvalidMappingException ('Could not parse mapping document: %s (%s') with the Origin. It is the umbrella error for reading a mapping document from a stream: StAX reader failures, root-element problems, JAXB unmarshalling and schema-validation errors all land here.","triggerScenarios":"Adding a mapping via stream (addResource from classpath, URL, etc.) where the document fails at any binding stage: not well-formed, wrong root/namespace, XSD violations, or unmarshal type errors.","commonSituations":"Classpath mappings edited by hand; documents copied from other Hibernate versions; encoding damage in transit; any of the lower-level causes (StAX/JAXB) reached via stream-based APIs.","solutions":["Unwrap getCause() - it is the specific StAX/JAXB/root-element failure with position detail","Open the document named by the Origin and validate it (well-formedness first, then against the Hibernate XSD)","Fix the reported construct, or align the document's namespace/version with the Hibernate version in use","If the stream itself is the problem (already consumed/closed), pass a fresh stream"],"exampleFix":"// before\ntry {\n    sources.addResource(name); // throws InvalidMappingException\n} catch (InvalidMappingException e) { /* only message kept, cause lost */ }\n\n// after: keep the cause for diagnosis\ntry {\n    sources.addResource(name);\n} catch (InvalidMappingException e) {\n    throw new IllegalStateException(\"Bad mapping \" + name, e.getCause());\n}","handlingStrategy":"try-catch","validationCode":"// pre-flight: parse the document exactly as the binder will\ntry (InputStream in = openMappingStream(name)) {\n    javax.xml.parsers.DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(in);\n} catch (Exception e) {\n    throw new IllegalArgumentException(\"Mapping '\" + name + \"' fails pre-parse: \" + e.getMessage(), e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadataSources.addResource(name);\n} catch (InvalidMappingException e) {\n    // unwrap: the cause is the specific StAX/JAXB failure with line info\n    log.error(\"Invalid mapping {} : {}\", name, e.getCause().getMessage(), e.getCause());\n    throw e;\n}","preventionTips":["Always unwrap and log InvalidMappingException.getCause()","Add an XML well-formedness/XSD check for mappings to CI","Re-run a smoke bootstrap in CI so broken mappings fail the build, not production"],"tags":["hibernate","mapping-file","xml-parsing","jaxb","bootstrap"],"backgroundTag":"jaxb-unmarshal-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}