{"record":{"id":"f76da77b2647225b","repo":"quarkusio/quarkus","slug":"an-extension-attempted-to-contribute-the-default-p","errorCode":null,"errorMessage":"An extension attempted to contribute the default persistence unit through the SPI. Contributed persistence units must use a non-default name.","messagePattern":"An extension attempted to contribute the default persistence unit through the SPI\\. Contributed persistence units must use a non-default name\\.","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmProcessor.java","lineNumber":442,"sourceCode":"            HibernateOrmConfig hibernateOrmConfig,\n            List<PersistenceXmlDescriptorBuildItem> persistenceXmlDescriptors,\n            List<JdbcDataSourceBuildItem> jdbcDataSources,\n            List<AdditionalPersistenceUnitBuildItem> additionalPersistenceUnits,\n            JpaModelPerPersistenceUnitBuildItem jpaModel,\n            Capabilities capabilities,\n            BuildProducer<PersistenceUnitDescriptorBuildItem> persistenceUnitDescriptors,\n            List<DefaultDataSourceDbVersionBuildItem> defaultDbVersions) {\n        // TODO move this validation to a dedicated method, preferably very early in the build?\n        //   See also a conceptually similar check in contributeQuarkusConfigToJpaModel\n        if (!additionalPersistenceUnits.isEmpty()) {\n            Set<String> userConfiguredPersistenceUnitNames = new HashSet<>(hibernateOrmConfig.namedPersistenceUnits().keySet());\n            for (PersistenceXmlDescriptorBuildItem persistenceXmlDescriptor : persistenceXmlDescriptors) {\n                userConfiguredPersistenceUnitNames.add(persistenceXmlDescriptor.getDescriptor().getName());\n            }\n            for (AdditionalPersistenceUnitBuildItem additionalPersistenceUnit : additionalPersistenceUnits) {\n                String persistenceUnitName = additionalPersistenceUnit.getPersistenceUnitName();\n                if (PersistenceUnitUtil.isDefaultPersistenceUnit(persistenceUnitName)) {\n                    throw new ConfigurationException(\n                            \"An extension attempted to contribute the default persistence unit through the SPI.\"\n                                    + \" Contributed persistence units must use a non-default name.\");\n                }\n                if (userConfiguredPersistenceUnitNames.contains(persistenceUnitName)) {\n                    throw new ConfigurationException(String.format(Locale.ROOT,\n                            \"Persistence unit '%s' is contributed by an extension but is also configured by the application.\"\n                                    + \" A persistence unit contributed through the SPI must use a name that is not already\"\n                                    + \" configured through Quarkus configuration or a persistence.xml file.\",\n                            persistenceUnitName));\n                }\n            }\n        }\n\n        // Produce the PUs having a persistence.xml: these are not reactive, as we don't allow using a persistence.xml for them.\n        for (PersistenceXmlDescriptorBuildItem persistenceXmlDescriptorBuildItem : persistenceXmlDescriptors) {\n            PersistenceUnitDescriptor xmlDescriptor = persistenceXmlDescriptorBuildItem.getDescriptor();\n            String puName = xmlDescriptor.getName();\n            Optional<JdbcDataSourceBuildItem> jdbcDataSource = findDefaultDataSource(jdbcDataSources);","sourceCodeStart":424,"sourceCodeEnd":460,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmProcessor.java#L424-L460","documentation":"Quarkus extensions can contribute additional persistence units via the AdditionalPersistenceUnitBuildItem SPI, but the default persistence unit (empty name) must be owned by the application's configuration or persistence.xml, not by an extension. During HibernateOrmProcessor.buildBlockingPersistenceUnitFromPersistenceXml a ConfigurationException is thrown if an extension attempts to contribute a PU with the default name.","triggerScenarios":"A custom Quarkus extension produces an AdditionalPersistenceUnitBuildItem whose persistenceUnitName is null or empty (i.e. PersistenceUnitUtil.isDefaultPersistenceUnit returns true) while persistence.xml descriptors are processed.","commonSituations":"Writing an in-house extension that reuses the Hibernate ORM SPI and forgetting to set a persistence unit name; copying sample code that omits the name parameter.","solutions":["Set a distinct non-null, non-empty name on the AdditionalPersistenceUnitBuildItem in your extension","If the intent was to configure the default PU, do it via quarkus.hibernate-orm.* application configuration or persistence.xml instead of the SPI"],"exampleFix":"// before\nnew AdditionalPersistenceUnitBuildItem(null, ...)\n// after\nnew AdditionalPersistenceUnitBuildItem(\"audit\", ...)","handlingStrategy":"validation","validationCode":"if (puName == null || puName.isBlank()) {\n    throw new IllegalArgumentException(\"AdditionalPersistenceUnitBuildItem requires a non-default name\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always give SPI-contributed persistence units an explicit, descriptive name","Never pass null/empty as persistenceUnitName in AdditionalPersistenceUnitBuildItem","Configure the default PU only through quarkus.hibernate-orm.* or persistence.xml"],"tags":["hibernate-orm","persistence-unit","spi","build-time"],"backgroundTag":"default-persistence-unit-name-conflict","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}