{"record":{"id":"1835426dad0e1ded","repo":"quarkusio/quarkus","slug":"multiple-instances-of-1-s-were-found-for-persiste","errorCode":null,"errorMessage":"Multiple instances of %1$s were found for persistence unit %2$s. At most one instance can be assigned to each persistence unit. Instances found: %3$s","messagePattern":"Multiple instances of %1\\$s were found for persistence unit %2\\$s\\. At most one instance can be assigned to each persistence unit\\. Instances found: %3\\$s","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/PersistenceUnitUtil.java","lineNumber":48,"sourceCode":"\n    public static Annotation qualifier(String persistenceUnitName) {\n        if (isDefaultPersistenceUnit(persistenceUnitName)) {\n            return Default.Literal.INSTANCE;\n        } else {\n            return new PersistenceUnit.PersistenceUnitLiteral(persistenceUnitName);\n        }\n    }\n\n    public static <T> InjectableInstance<T> singleExtensionInstanceForPersistenceUnit(\n            Class<T> beanType,\n            String persistenceUnitName,\n            Annotation... additionalQualifiers) {\n        InjectableInstance<T> instance = extensionInstancesForPersistenceUnit(beanType, persistenceUnitName,\n                additionalQualifiers);\n        if (instance.isAmbiguous()) {\n            List<String> ambiguousClassNames = instance.handlesStream().map(h -> h.getBean().getBeanClass().getCanonicalName())\n                    .toList();\n            throw new IllegalStateException(String.format(Locale.ROOT,\n                    \"Multiple instances of %1$s were found for persistence unit %2$s. \"\n                            + \"At most one instance can be assigned to each persistence unit. Instances found: %3$s\",\n                    beanType.getSimpleName(), persistenceUnitName, ambiguousClassNames));\n        }\n        return instance;\n    }\n\n    public static <T> InjectableInstance<T> extensionInstancesForPersistenceUnit(\n            Class<T> beanType,\n            String persistenceUnitName,\n            Annotation... additionalQualifiers) {\n        if (additionalQualifiers.length == 0) {\n            return Arc.container().select(beanType, new PersistenceUnitExtension.Literal(persistenceUnitName));\n        } else {\n            Annotation[] qualifiers = Arrays.copyOf(additionalQualifiers, additionalQualifiers.length + 1);\n            qualifiers[additionalQualifiers.length] = new PersistenceUnitExtension.Literal(persistenceUnitName);\n            return Arc.container().select(beanType, qualifiers);\n        }","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/PersistenceUnitUtil.java#L30-L66","documentation":"PersistenceUnitUtil enforces that at most one bean of a given extension type (e.g. a single Persistencer/KnownPersistenceUnit holder or interceptor) is assigned to a given persistence unit. When the CDI InjectableInstance for (beanType, PU name, qualifiers) resolves ambiguously — multiple beans match — this IllegalStateException is thrown listing all found bean classes.","triggerScenarios":"Declaring two CDI beans of the same extension interface/class (e.g. two custom Persisters, two TenantConnectionProviders) both applicable to the same PU; beans with qualifiers that don't exclude each other; accidentally annotating a second class with the same @PersistenceUnitExtension qualifier/scope.","commonSituations":"Multi-tenancy setups where a developer adds a second extension bean per tenant but forgets @PersistenceUnitExtensionqualifiers; copy-pasting a CDI bean class; @Alternative not declared so both beans are enabled.","solutions":["Keep exactly one bean of that type per persistence unit, or annotate each with a distinct @PersistenceUnitExtension qualifier (e.g. @ReactiveTenantConnectionResolver variants).","Use @Alternative/@Priority to disable one of the duplicate beans.","Inspect the 'Instances found' list in the message and remove or qualify the redundant class.","For multi-PU apps, narrow each bean with @PersistenceUnitExtension(persistenceUnitName = \"...\")."],"exampleFix":"// before (two beans for same PU)\n@PersistenceUnitExtension class MyProviderA implements ... {}\n@PersistenceUnitExtension class MyProviderB implements ... {}\n// after\n@PersistenceUnitExtension(persistenceUnitName = \"pu1\") class MyProviderA implements ... {}\n@PersistenceUnitExtension(persistenceUnitName = \"pu2\") class MyProviderB implements ... {}","handlingStrategy":"validation","validationCode":"// Validate unambiguity at startup instead of at first use\nInjectableInstance<T> i = instance.select(beanType, qualifiers);\nif (i.isAmbiguous()) { throw new IllegalArgumentException(\"Multiple \" + beanType + \" beans for PU\"); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["One extension bean per persistence unit; use @PersistenceUnitExtension qualifiers to disambiguate","Review the 'Instances found' list to locate the duplicate class quickly","Use @Alternative + @Priority when overriding a built-in extension bean"],"tags":["cdi","ambiguous-bean","hibernate-orm","quarkus","persistence-unit"],"backgroundTag":"ambiguous-cdi-bean","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"}