{"record":{"id":"81a780c309a02e74","repo":"hibernate/hibernate-orm","slug":"unable-to-locate-persistence-units","errorCode":null,"errorMessage":"Unable to locate persistence units","messagePattern":"Unable to locate persistence units","errorType":"exception","errorClass":"PersistenceException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceProvider.java","lineNumber":159,"sourceCode":"\t\t\tClassLoader providedClassLoader,\n\t\t\tClassLoaderService providedClassLoaderService) {\n\t\ttry {\n\t\t\tfinal var parser =\n\t\t\t\t\tPersistenceXmlParser.create( integration, providedClassLoader, providedClassLoaderService );\n\t\t\tfinal var xmlUrls =\n\t\t\t\t\tparser.getClassLoaderService()\n\t\t\t\t\t\t\t.locateResources( \"META-INF/persistence.xml\" );\n\t\t\tif ( xmlUrls.isEmpty() ) {\n\t\t\t\tJPA_LOGGER.unableToFindPersistenceXmlInClasspath();\n\t\t\t\treturn List.of();\n\t\t\t}\n\t\t\telse {\n\t\t\t\treturn parser.parse( xmlUrls ).values();\n\t\t\t}\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tJPA_LOGGER.unableToLocatePersistenceUnits( e );\n\t\t\tthrow new PersistenceException( \"Unable to locate persistence units\", e );\n\t\t}\n\t}\n\n\t/**\n\t * {@inheritDoc}\n\t *\n\t * @implSpec The values passed in the {@code map} override values found\n\t *           in {@link PersistenceUnitInfo#getProperties()} according to\n\t *           the JPA specification.\n\t */\n\t@Override\n\tpublic EntityManagerFactory createContainerEntityManagerFactory(PersistenceUnitInfo info, Map<?,?> map) {\n\t\tJPA_LOGGER.startingCreateContainerEntityManagerFactory( info.getPersistenceUnitName() );\n\t\treturn getEntityManagerFactoryBuilder( info, map ).build();\n\t}\n\n\t/**\n\t * {@inheritDoc}","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceProvider.java#L141-L177","documentation":"locatePersistenceUnits wraps any failure of the persistence.xml scan/parse pipeline in PersistenceException(\"Unable to locate persistence units\", e). Note the distinction: when NO persistence.xml is found at all, Hibernate logs and returns an empty list - this exception means a persistence.xml WAS located but scanning/parsing it failed, and the cause carries the real problem.","triggerScenarios":"A malformed persistence.xml (unbalanced tags, bad entity references), a document whose XSD version the parser rejects (e.g. a 2.x schema on a Jakarta 3.x Hibernate), duplicate/invalid unit declarations, or a ClassLoaderService failure while reading the located resources.","commonSituations":"Hand-edited persistence.xml with XML typos; mixing JPA 2.x persistence.xml with Hibernate 6+/Jakarta; two versions of hibernate-core on the classpath fighting over the parser; encoding issues in the XML.","solutions":["Inspect the wrapped cause - it names the file and the exact XML/parse problem","Validate each persistence.xml against the Jakarta Persistence XSD matching your Hibernate version, and fix the reported construct","Run 'mvn dependency:tree' / 'gradle dependencies' and exclude the older hibernate-core/javax.persistence that brought an incompatible parser or schema"],"exampleFix":"<!-- before: 2.x schema with Jakarta Hibernate 6+ -->\n<persistence xmlns=\"http://java.sun.com/xml/ns/persistence\" version=\"2.1\">...</persistence>\n\n<!-- after -->\n<persistence xmlns=\"https://jakarta.ee/xml/ns/persistence\" version=\"3.0\">...</persistence>","handlingStrategy":"try-catch","validationCode":"// optional: parse-check persistence.xml before bootstrapping\ntry {\n    javax.xml.parsers.DocumentBuilderFactory.newInstance().newDocumentBuilder()\n        .parse(cl.getResourceAsStream(\"META-INF/persistence.xml\"));\n} catch (Exception e) {\n    throw new IllegalStateException(\"persistence.xml is not well-formed\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    EntityManagerFactory emf = Persistence.createEntityManagerFactory(\"main\");\n} catch (javax.persistence.PersistenceException | jakarta.persistence.PersistenceException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Unable to locate persistence units\")) {\n        Throwable cause = e.getCause(); // the actual parse error - fix persistence.xml accordingly\n        throw new IllegalStateException(\"Bad persistence.xml: \" + cause, e);\n    }\n    throw e;\n}","preventionTips":["Validate persistence.xml against the Jakarta Persistence XSD in CI (xmllint)","Keep exactly one hibernate-core/jpa version on the classpath","Edit XML with schema-aware tooling to avoid namespace/version drift"],"tags":["jpa","bootstrap","persistence-xml","xml-parse"],"backgroundTag":"persistence-xml-parse-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}