{"record":{"id":"33d69b19ebf5351c","repo":"quarkusio/quarkus","slug":"hibernate-s-persistence-unit-s-cannot-be-creat","errorCode":null,"errorMessage":"Hibernate %s persistence unit '%s' cannot be created for the following reason(s):\n%s\nRefer to https://quarkus.io/guides/datasource for guidance.\nThis persistence unit is being created because of:\n%s\n","messagePattern":"Hibernate (.+?) persistence unit '(.+?)' cannot be created for the following reason\\(s\\):\n(.+?)\nRefer to https://quarkus\\.io/guides/datasource for guidance\\.\nThis persistence unit is being created because of:\n(.+?)\n","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/component/PersistenceUnitDefinitionSupport.java","lineNumber":185,"sourceCode":"                            item.getExplicitDialect(), item.getProperties()));\n            if (previous != null) {\n                throw new IllegalStateException(\"Multiple \" + AdditionalPersistenceUnitBuildItem.class.getSimpleName()\n                        + \" for persistence unit '\" + puName + \"'\");\n            }\n        }\n\n        if (LOG.isDebugEnabled()) {\n            LOG.debugf(\"Defining %s persistence units; reasons:\\n%s\", paradigm,\n                    puNamesWithReasons.entrySet().stream()\n                            .map(e -> e.getKey() + \": \" + Reason.format(e.getValue()))\n                            .collect(Collectors.joining(\"\\n\")));\n        }\n        for (var entry : puNamesWithReasons.entrySet()) {\n            String puName = entry.getKey();\n\n            List<Reason> unavailableReasons = lookupBuildItem.getLookup().unavailableReasons(puName, paradigm);\n            if (!unavailableReasons.isEmpty()) {\n                throw new ConfigurationException(String.format(Locale.ROOT,\n                        \"\"\"\n                                Hibernate %s persistence unit '%s' cannot be created for the following reason(s):\n                                %s\n                                Refer to https://quarkus.io/guides/datasource for guidance.\n                                This persistence unit is being created because of:\n                                %s\n                                \"\"\",\n                        switch (paradigm) {\n                            case BLOCKING -> \"ORM\";\n                            case REACTIVE -> \"Reactive\";\n                        },\n                        puName,\n                        Reason.format(unavailableReasons),\n                        Reason.format(entry.getValue())));\n            }\n\n            PersistenceUnitDefinitionBuildItem.AdditionalConfig additionalConfig = additionalConfigs.get(puName);\n            Optional<String> dataSourceName = additionalConfig != null","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/component/PersistenceUnitDefinitionSupport.java#L167-L203","documentation":"Quarkus aborts the build when a Hibernate persistence unit is requested (because of active config/annotations) but cannot be created, e.g. its configured datasource is missing or the dialect is unavailable. ConfigurationException lists all unavailable reasons, a link to the datasource guide, and the reasons why the PU was being created at all.","triggerScenarios":"definePersistenceUnits finds unavailableReasons for a PU from the lookup build item (for the paradigm, e.g. blocking or reactive), such as a nonexistent or misconfigured datasource name, while the PU is still demanded by application config or annotations.","commonSituations":"quarkus.datasource.\"name\" not defined but referenced by quarkus.hibernate-orm.\"pu\".datasource; datasource extension not present; typos between datasource name and PU config; activating Hibernate without any datasource at all.","solutions":["Define the referenced datasource (quarkus.datasource.\"name\".db-kind=..., username, jdbc-url) or fix the datasource name typo in the PU config","Add the quarkus-jdbc-<db> driver extension matching db-kind","If the PU is unintended, remove the config/annotations that cause it to be created","Read the listed unavailableReasons and the 'because of' reasons in the message to pinpoint the cause"],"exampleFix":"// before\nquarkus.hibernate-orm.\"pu1\".datasource=missing-ds\n// after\nquarkus.datasource.\"missing-ds\".db-kind=postgresql\nquarkus.datasource.\"missing-ds\".username=app\nquarkus.datasource.\"missing-ds\".jdbc-url=jdbc:postgresql://localhost:5432/appdb\nquarkus.hibernate-orm.\"pu1\".datasource=missing-ds","handlingStrategy":"validation","validationCode":"// Before startup: assert every referenced datasource exists\nSet<String> referenced = Set.of(\"missing-ds\");\nSet<String> defined = Set.of(\"<default>\");\nif (!defined.containsAll(referenced))\n    throw new IllegalStateException(\"Datasources not defined: \" + referenced);\n// and in tests use @QuarkusTest with the datasource extension present","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Define every named datasource referenced by a PU before adding ORM config","Always include a quarkus-jdbc-<db> driver extension","Keep PU datasource names in one place and cross-check in CI"],"tags":["quarkus","hibernate-orm","datasource","configuration-exception"],"backgroundTag":"missing-datasource-configuration","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}