quarkusio/quarkus · error · ConfigurationException

Not possible to define the scope %s for the REST client %s

Error message

Not possible to define the scope %s for the REST client %s 

What it means

During REST client build-time configuration processing, Quarkus maps the scope name given via @RegisterRestClient(configKey=...) / rest-client config 'scope' property to a known CDI BuiltinScope. If the configured scope name does not match any builtin scope (case-insensitively), the build fails with a ConfigurationException naming the scope and the REST client class.

Source

Thrown at extensions/resteasy-classic/rest-client-config/deployment/src/main/java/io/quarkus/restclient/config/deployment/RestClientsBuildTimeConfigBuildItem.java:151

            } else {
                return scope;
            }
        }
        return Optional.empty();
    }

    private static Optional<BuiltinScope> builtinScopeFromName(DotName scopeName, String restClientClass) {
        BuiltinScope scope = BuiltinScope.from(scopeName);
        if (scope != null) {
            return Optional.of(scope);
        }

        for (BuiltinScope builtinScope : BuiltinScope.values()) {
            if (builtinScope.getName().withoutPackagePrefix().equalsIgnoreCase(scopeName.toString())) {
                return Optional.of(builtinScope);
            }
        }
        throw new ConfigurationException(
                String.format("Not possible to define the scope %s for the REST client %s ", scopeName, restClientClass));
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Set scope to a builtin simple name without '@': ApplicationScoped, RequestScoped, Dependent, or Singleton (case-insensitive)
2. Remove the '@' prefix and package prefix from the configured value
3. If a custom scope is required, register it properly and check whether Quarkus supports it for REST clients, otherwise wrap the client in a producer bean with the custom scope
4. Verify the exact configured key in application.properties matches the client's configKey

Example fix

// before
quarkus.rest-client.my-client.scope=@ApplicationScoped
// after
quarkus.rest-client.my-client.scope=ApplicationScoped

static final Set<String> BUILTIN = Set.of("applicationscoped","requestscoped","dependent","singleton");
if (!BUILTIN.contains(scope.toLowerCase().replace("@", "")))
    throw new IllegalStateException("Unsupported REST client scope: " + scope);

// Build-time failure: fix configuration, cannot be caught at runtime.
// Catch org.eclipse.microprofile.config.ConfigException / ConfigurationException during startup to fail with a clearer message.

When it happens

Trigger: Setting quarkus.rest-client.<key>.scope (or @RegisterRestClient scope attribute) to a value that is not one of: jakarta.enterprise.context.ApplicationScoped, RequestScoped, Dependent, Singleton — e.g. typos like 'appscoped', '@Singleton' with the '@' prefix, or a custom scope not registered in the app.

Common situations: Copy-pasting a scope annotation name including '@'; using a custom @Scope without it being discoverable at build time; upgrading Quarkus where javax->jakarta prefix changed the expected canonical name; confusing 'singleton' with 'jakarta.inject.Singleton' (matching is on the simple name of builtin scopes).

Related errors

• @CachedResults class must be an interface or declare a no-ar
• 'quarkus-narayana-lra' can only work if 'quarkus-rest-client
• Method ${class}#${method} has an unsupported return type for
• Method ${class}#${method} has an unsupported return type for
• Unknown node type ${type}

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