What causes "Components annotated with multiple conflicting scopes must declare an explicit @Scope. declares scopes: through the stereotypes: " in quarkusio/quarkus?

Add an explicit @Scope (e.g. @Scope("singleton") or @Scope("prototype")) to the class

quarkusio/quarkus · error · DefinitionException

Components annotated with multiple conflicting scopes must d

Error message

Components annotated with multiple conflicting scopes must declare an explicit @Scope. <class> declares scopes: <scopes> through the stereotypes: <stereotypes>

What it means

A Spring bean uses multiple scope-carrying annotations (e.g. via custom stereotype/composed annotations) that each declare a different scope, so the translated CDI bean has ambiguous scope. The Spring DI processor requires an explicit @Scope on the class to disambiguate.

Source

Thrown at extensions/spring-di/deployment/src/main/java/io/quarkus/spring/di/deployment/SpringDIProcessor.java:636

    /**
     * Get a single scope from the available options or throw a {@link DefinitionException} explaining
     * where the annotations conflict.
     *
     * @param clazz The class annotated with the scopes
     * @param scopes The scopes from the class and its stereotypes
     * @param scopeStereotypes The stereotype annotations that declared the conflicting scopes
     * @return The scope for the target class
     */
    private DotName validateScope(final ClassInfo clazz, final Set<DotName> scopes, final Set<DotName> scopeStereotypes) {
        final int size = scopes.size();
        switch (size) {
            case 0:
                // Spring default
                return CDI_SINGLETON_ANNOTATION;
            case 1:
                return scopes.iterator().next();
            default:
                throw new DefinitionException(
                        "Components annotated with multiple conflicting scopes must declare an explicit @Scope. "
                                + clazz.name() + " declares scopes: "
                                + scopes.stream().map(DotName::toString).collect(Collectors.joining(", "))
                                + " through the stereotypes: "
                                + scopeStereotypes.stream().map(DotName::toString)
                                        .collect(Collectors.joining(", ")));
        }
    }

    /**
     * Get the name of a bean or throw a {@link DefinitionException} if it has more than one name
     *
     * @param clazz The class annotated with the names
     * @param names The names
     * @return The bane name
     */
    private String validateName(final ClassInfo clazz, final Set<String> names) {
        final int size = names.size();

View on GitHub (pinned to e1c734241f)

Solutions

Add an explicit @Scope (e.g. @Scope("singleton") or @Scope("prototype")) to the class
Remove one of the conflicting scope-bearing stereotype annotations
Refactor the stereotypes so all declare the same scope

Example fix

// before
@Component
@MyTransactionalStereotype
@MyRequestStereotype
class MyService {}

// after
@Component
@Scope("prototype")
@MyTransactionalStereotype
@MyRequestStereotype
class MyService {}

Defensive patterns

Strategy: validation

Validate before calling

Set<Annotation> scopes = getScopeBearingAnnotations(clazz);
if (scopes.stream().map(s -> resolveScope(s)).distinct().count() > 1 && !clazz.isAnnotationPresent(Scope.class)) {
    throw new IllegalStateException("Add explicit @Scope to " + clazz.getName());
}

Prevention

Keep at most one scope-bearing stereotype per component
Always declare @Scope explicitly when using multiple stereotypes
Document custom stereotypes' scopes to avoid conflicts

When it happens

Trigger: Annotating a @Component/@Service class with two or more annotations whose meta-annotations declare different scopes (e.g. a @Transactional-style stereotype plus a request-scoped stereotype) without an explicit @Scope on the class.

Common situations: Migrating Spring projects that define custom stereotype annotations with meta-scopes; accidentally stacking scope-bearing annotations; copy-pasted annotations on service classes.

Related errors

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