quarkusio/quarkus · error · ConfigurationException

Datasource must be defined for persistence unit '%s'. Settin

Error message

Datasource must be defined for persistence unit '%s'. Setting the datasource for the persistence unit can be done via the '%s' property.  Refer to https://quarkus.io/guides/datasource for guidance.

What it means

Each persistence unit needs a datasource. When multi-tenancy is not DATABASE and no JdbcDataSourceBuildItem was found for the persistence unit, HibernateOrmProcessor throws a ConfigurationException telling you which property (quarkus.hibernate-orm."<pu>".datasource or the default PU equivalent) to set, and marks the required datasource config properties.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmProcessor.java:1202

                        isHibernateValidatorPresent(capabilities)));
    }

    private static Optional<DatabaseKind.SupportedDatabaseKind> collectDialectConfig(String persistenceUnitName,
            HibernateOrmConfigPersistenceUnit persistenceUnitConfig,
            List<DatabaseKindDialectBuildItem> dbKindMetadataBuildItems,
            Optional<JdbcDataSourceBuildItem> jdbcDataSource,
            MultiTenancyStrategy multiTenancyStrategy,
            Optional<String> dialect,
            BuildProducer<ReflectiveMethodBuildItem> reflectiveMethods,
            BiConsumer<String, String> puPropertiesCollector) {
        final HibernateOrmConfigPersistenceUnit.HibernateOrmConfigPersistenceUnitDialect dialectConfig = persistenceUnitConfig
                .dialect();

        Optional<String> dbKind = jdbcDataSource.map(JdbcDataSourceBuildItem::getDbKind);
        Optional<String> dbVersion = jdbcDataSource.flatMap(JdbcDataSourceBuildItem::getDbVersion);
        if (multiTenancyStrategy != MultiTenancyStrategy.DATABASE && jdbcDataSource.isEmpty()) {
            String dsConfigProperty = HibernateOrmRuntimeConfig.puPropertyKey(persistenceUnitName, "datasource");
            throw new ConfigurationException(String.format(Locale.ROOT,
                    "Datasource must be defined for persistence unit '%s'. Setting the datasource for the persistence unit can be done via the '%s' property. "
                            + " Refer to https://quarkus.io/guides/datasource for guidance.",
                    persistenceUnitName, dsConfigProperty),
                    new HashSet<>(Arrays.asList("quarkus.datasource.db-kind", "quarkus.datasource.username",
                            "quarkus.datasource.password", "quarkus.datasource.jdbc.url")));
        }

        Optional<DatabaseKind.SupportedDatabaseKind> supportedDatabaseKind = setDialectAndStorageEngine(
                persistenceUnitName,
                dbKind,
                dialect,
                dbVersion,
                dialectConfig,
                dbKindMetadataBuildItems,
                puPropertiesCollector);

        if ((dbKind.isPresent() && DatabaseKind.isPostgreSQL(dbKind.get())
                || (dialect.isPresent() && dialect.get().toLowerCase(Locale.ROOT).contains("postgres")))) {

View on GitHub (pinned to e1c734241f)

Solutions

Define a datasource in application.properties (quarkus.datasource.db-kind, username, password, jdbc.url) or the PU-specific quarkus.hibernate-orm."<pu>".datasource
Add the matching JDBC driver extension (e.g. quarkus-jdbc-postgresql)
Fix a misspelled datasource name in the PU configuration

Example fix

// application.properties
// before
quarkus.hibernate-orm.datasource.name=missing-ds
// after
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=app
quarkus.datasource.password=secret
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/appdb

Defensive patterns

Strategy: validation

Validate before calling

// application.properties must define, for PU '<pu>':
// quarkus.hibernate-orm."<pu>".datasource=<ds> and quarkus.datasource."<ds>".* settings
assertNotBlank(prop("quarkus.datasource.jdbc.url"), "Datasource must be defined before build");

Prevention

Always configure quarkus.datasource.db-kind and jdbc.url when using Hibernate ORM
Add the JDBC driver extension (quarkus-jdbc-*) for your database
When adding a second persistence unit, define and reference its datasource explicitly

When it happens

Trigger: Building a persistence unit whose multiTenancyStrategy != DATABASE while no JDBC datasource build item exists, i.e. quarkus.datasource.* is not configured or quarkus.hibernate-orm.datasource is unset/points to a missing datasource.

Common situations: Forgetting to add the quarkus-jdbc-* driver extension and datasource config; typo in the datasource name referenced by the PU; new PU added for a second database with no datasource defined.

Related errors

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