quarkusio/quarkus · error · ConfigurationException

Hibernate %s persistence unit '%s' cannot be created for the

Error message

Hibernate %s persistence unit '%s' cannot be created for the following reason(s):
%s
Refer to https://quarkus.io/guides/datasource for guidance.
This persistence unit is being created because of:
%s

What it means

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.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/component/PersistenceUnitDefinitionSupport.java:185

                            item.getExplicitDialect(), item.getProperties()));
            if (previous != null) {
                throw new IllegalStateException("Multiple " + AdditionalPersistenceUnitBuildItem.class.getSimpleName()
                        + " for persistence unit '" + puName + "'");
            }
        }

        if (LOG.isDebugEnabled()) {
            LOG.debugf("Defining %s persistence units; reasons:\n%s", paradigm,
                    puNamesWithReasons.entrySet().stream()
                            .map(e -> e.getKey() + ": " + Reason.format(e.getValue()))
                            .collect(Collectors.joining("\n")));
        }
        for (var entry : puNamesWithReasons.entrySet()) {
            String puName = entry.getKey();

            List<Reason> unavailableReasons = lookupBuildItem.getLookup().unavailableReasons(puName, paradigm);
            if (!unavailableReasons.isEmpty()) {
                throw new ConfigurationException(String.format(Locale.ROOT,
                        """
                                Hibernate %s persistence unit '%s' cannot be created for the following reason(s):
                                %s
                                Refer to https://quarkus.io/guides/datasource for guidance.
                                This persistence unit is being created because of:
                                %s
                                """,
                        switch (paradigm) {
                            case BLOCKING -> "ORM";
                            case REACTIVE -> "Reactive";
                        },
                        puName,
                        Reason.format(unavailableReasons),
                        Reason.format(entry.getValue())));
            }

            PersistenceUnitDefinitionBuildItem.AdditionalConfig additionalConfig = additionalConfigs.get(puName);
            Optional<String> dataSourceName = additionalConfig != null

View on GitHub (pinned to e1c734241f)

Solutions

1. Define the referenced datasource (quarkus.datasource."name".db-kind=..., username, jdbc-url) or fix the datasource name typo in the PU config
2. Add the quarkus-jdbc-<db> driver extension matching db-kind
3. If the PU is unintended, remove the config/annotations that cause it to be created
4. Read the listed unavailableReasons and the 'because of' reasons in the message to pinpoint the cause

Example fix

// before
quarkus.hibernate-orm."pu1".datasource=missing-ds
// after
quarkus.datasource."missing-ds".db-kind=postgresql
quarkus.datasource."missing-ds".username=app
quarkus.datasource."missing-ds".jdbc-url=jdbc:postgresql://localhost:5432/appdb
quarkus.hibernate-orm."pu1".datasource=missing-ds

// Before startup: assert every referenced datasource exists
Set<String> referenced = Set.of("missing-ds");
Set<String> defined = Set.of("<default>");
if (!defined.containsAll(referenced))
    throw new IllegalStateException("Datasources not defined: " + referenced);
// and in tests use @QuarkusTest with the datasource extension present

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to load the datasource driver <driverName> for the <f
• No datasource named '<dataSourceName>' exists
• Datasource <dataSourceName> does not have a JDBC URL and sho
• Unable to load the datasource driver <resolvedDriverClass> f
• quarkus.datasource.url and quarkus.datasource.driver have be

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/33d69b19ebf5351c. Report an issue: GitHub.