quarkusio/quarkus · error · DefinitionException

Stereotype must not declare @Named with a non-empty value: $

Error message

Stereotype must not declare @Named with a non-empty value: ${stereotypeClass}

What it means

Per CDI, a stereotype must not declare @Named with a non-empty value (a stereotype can only mark the bean named, not fix its name). During BeanDeployment stereotype metadata processing, Arc throws DefinitionException if a @Named annotation on a stereotype class carries a value.

Source

Thrown at independent-projects/arc/processor/src/main/java/io/quarkus/arc/processor/BeanDeployment.java:1024

                boolean isAlternative = false;
                Integer alternativePriority = null;
                Set<ScopeInfo> scopes = new HashSet<>();
                List<AnnotationInstance> bindings = new ArrayList<>();
                List<AnnotationInstance> parentStereotypes = new ArrayList<>();
                boolean isNamed = false;

                for (AnnotationInstance annotation : annotationStore.getAnnotations(stereotypeClass)) {
                    if (DotNames.ALTERNATIVE.equals(annotation.name())) {
                        isAlternative = true;
                    } else if (interceptorBindings.containsKey(annotation.name())) {
                        bindings.add(annotation);
                    } else if (stereotypeNames.contains(annotation.name())) {
                        parentStereotypes.add(annotation);
                    } else if (DotNames.NAMED.equals(annotation.name())) {
                        if (annotation.value() != null && !annotation.value()
                                .asString()
                                .isEmpty()) {
                            throw new DefinitionException(
                                    "Stereotype must not declare @Named with a non-empty value: " + stereotypeClass);
                        }
                        isNamed = true;
                    } else if (DotNames.PRIORITY.equals(annotation.name())) {
                        alternativePriority = annotation.value().asInt();
                    } else {
                        final ScopeInfo scope = getScope(annotation.name(), customContextScopes);
                        if (scope != null) {
                            scopes.add(scope);
                        }
                    }
                }
                boolean isAdditionalStereotype = additionalStereotypes.contains(stereotypeName);
                final ScopeInfo scope = getValidScope(scopes, stereotypeClass);
                boolean isInherited = stereotypeClass.declaredAnnotation(DotNames.INHERITED) != null;
                stereotypes.put(stereotypeName, new StereotypeInfo(scope, bindings, isAlternative, alternativePriority,
                        isNamed, isAdditionalStereotype, stereotypeClass, isInherited, parentStereotypes));
            }

View on GitHub (pinned to e1c734241f)

Solutions

Remove the value: use plain @Named inside the stereotype
Move the specific name onto the bean class instead of the stereotype
Remove @Named from the stereotype if naming isn't needed

Example fix

// before
@Stereotype @Named("myBean") @interface MyStereotype {}
// after
@Stereotype @Named @interface MyStereotype {}

Defensive patterns

Strategy: validation

Validate before calling

Named named = stereotypeClass.getAnnotation(Named.class);
if (named != null && !named.value().isEmpty()) throw new DefinitionException("Stereotype @Named must be empty");

Try / catch

try { deployment.init(); }
catch (DefinitionException e) { if (e.getMessage().contains("@Named")) log.error("Fix stereotype: use plain @Named"); throw e; }

Prevention

Inside stereotypes use @Named without a value
Put concrete bean names on the bean class, not the stereotype
Grep stereotypes for @Named("...") during code review

When it happens

Trigger: Declaring a stereotype like @Stereotype @Named("foo") public @interface MyStereotype {} — the value "foo" is illegal; an empty @Named("") or plain @Named is allowed.

Common situations: Copy-pasting @Named("x") onto a stereotype; combining controller/action-style naming patterns from other frameworks into stereotypes; upgrading from another CDI implementation that didn't enforce this.

Related errors

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