quarkusio/quarkus · error · IllegalArgumentException

A synthetic bean ${bean} was defined with invalid scope anno

Error message

A synthetic bean ${bean} was defined with invalid scope annotation - ${scopeName}. Please use one of the built-in scopes or a valid, registered custom scope.

What it means

Synthetic beans (registered programmatically via SyntheticBeanBuilder) may accidentally reference a scope annotation that was never registered in the deployment. Because synthetic beans bypass class-level validation, ArC validates the scope at generation time and throws IllegalArgumentException when the scope is unknown.

Source

Thrown at independent-projects/arc/processor/src/main/java/io/quarkus/arc/processor/Beans.java:1034

                                "%s is not proxyable because it has a private no-args constructor: %s.", classifier, bean)));
                    } else {
                        bean.getDeployment().deferUnproxyableErrorToRuntime(bean);
                    }
                }
            }
            if (returnTypeClass != null && bean.getScope().isNormal() && returnTypeClass.isSealed()) {
                if (failIfNotProxyable) {
                    errors.add(new DeploymentException(
                            String.format("%s must not have a return type that is sealed: %s", classifier, bean)));
                } else {
                    bean.getDeployment().deferUnproxyableErrorToRuntime(bean);
                }
            }
        } else if (bean.isSynthetic()) {
            // synth beans can accidentally be defined with a non-existing scope, throw exception in such case
            DotName scopeName = bean.getScope().getDotName();
            if (bean.getDeployment().getScope(scopeName) == null) {
                throw new IllegalArgumentException("A synthetic bean " + bean + " was defined with invalid scope annotation - "
                        + scopeName + ". Please use one of the built-in scopes or a valid, registered custom scope.");
            }
            // this is for synthetic beans that need to be proxied but their classes don't have no-args constructor
            ClassInfo beanClass = getClassByName(bean.getDeployment().getBeanArchiveIndex(), bean.getBeanClass());
            MethodInfo noArgsConstructor = beanClass.method(Methods.INIT);
            if (bean.getScope().isNormal() && !Modifier.isInterface(beanClass.flags()) && noArgsConstructor == null) {
                if (bean.getDeployment().transformUnproxyableClasses) {
                    DotName superName = beanClass.superName();
                    if (!DotNames.OBJECT.equals(superName)) {
                        ClassInfo superClass = bean.getDeployment().getBeanArchiveIndex().getClassByName(beanClass.superName());
                        if (superClass == null || !superClass.hasNoArgsConstructor()) {
                            // Bean class extends a class without no-args constructor
                            // It is not possible to generate a no-args constructor reliably
                            superName = null;
                        }
                    }
                    if (superName != null) {
                        if (!classesReceivingNoArgsCtor.contains(beanClass.name())) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Use a built-in scope (@Dependent, @ApplicationScoped, @Singleton, @RequestScoped) when registering the synthetic bean
2. Register the custom scope in your extension so BeanDeployment knows it (and add a runtime scope annotation/meta-annotation)
3. Fix the scope class reference (typo/wrong import) in the SyntheticBeanBuilder call

Example fix

// before
syntheticBean.addScope(MyUnregisteredScope.class);
// after
syntheticBean.addScope(ApplicationScoped.class); // or register the custom scope in the extension

// in an extension registering a synthetic bean
DotName scopeName = DotName.createSimple(scopeCls.getName());
if (deployment.getScope(scopeName) == null) {
    throw new IllegalStateException("Scope not registered for synthetic bean: " + scopeName);
}

try {
    syntheticBeans.register(...);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("invalid scope annotation")) {
        logger.errorf("Use a registered scope for synthetic bean: %s", e.getMessage());
    }
    throw e;
}

When it happens

Trigger: Beans (public validation block) processes a bean where bean.isSynthetic() and bean.getDeployment().getScope(scopeName) == null — the scope annotation on the synthetic bean has no corresponding registered scope in the BeanDeployment.

Common situations: Registering a synthetic bean with a custom scope annotation that lacks @Scope/meta-annotation registration or an extension that did not register the scope; typo in the scope class passed to SyntheticBeanBuilder; missing quarkus.arc component for a custom scope.

Related errors

• Unable to find the bean class in the index:
• Calling injectInterceptionProxy() more than once is invalid
• Producer field type is a parameterized type with a type vari
• Declaring class of a managed bean is generic, its scope must
• The cause of an inactive result must also be inactive

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