quarkusio/quarkus · error · IllegalArgumentException

Unable to lookup configuration for REST Client ${restClientI

Error message

Unable to lookup configuration for REST Client ${restClientInterface}. Please confirm if the REST Client is annotated with @RegisterRestClient

What it means

RestClientsConfig.getClient(Class) looks up the per-client configuration by the interface's fully-qualified name in the registered REST client keys. If the interface was never registered as a REST client (i.e. not discovered via @RegisterRestClient at build time), the lookup fails and an IllegalArgumentException is thrown telling the developer to check the annotation.

Source

Thrown at extensions/resteasy-classic/rest-client-config/runtime/src/main/java/io/quarkus/restclient/config/RestClientsConfig.java:314

    Optional<Boolean> alpn();

    /**
     * If {@code true}, the stacktrace of the invocation of the REST Client method is captured.
     * This stacktrace will be used if the invocation throws an exception
     */
    @WithDefault("false")
    boolean captureStacktrace();

    /**
     * Logging configuration.
     */
    RestClientLoggingConfig logging();

    default RestClientConfig getClient(final Class<?> restClientInterface) {
        if (RestClientKeysProvider.KEYS.contains(restClientInterface.getName())) {
            return clients().get(restClientInterface.getName());
        }
        throw new IllegalArgumentException("Unable to lookup configuration for REST Client " + restClientInterface.getName()
                + ". Please confirm if the REST Client is annotated with @RegisterRestClient");
    }

    interface RestClientLoggingConfig {
        /**
         * Scope of logging for the client.
         * <br/>
         * WARNING: beware of logging sensitive data
         * <br/>
         * The possible values are:
         * <ul>
         * <li>{@code request-response} - enables logging request and responses, including redirect responses</li>
         * <li>{@code all} - enables logging requests and responses and lower-level logging</li>
         * <li>{@code none} - no additional logging</li>
         * </ul>
         *
         * This property is not applicable to the Quarkus RESTEasy client (provided by the quarkus-resteasy-client dependency).
         */

View on GitHub (pinned to e1c734241f)

Solutions

1. Annotate the interface with @RegisterRestClient
2. Verify the class passed to getClient()/injected is exactly the registered interface (same FQCN), not a similarly-named copy
3. Ensure the interface is in a package included in the application (indexed by Jandex); add the module/dependency to the app if it lives elsewhere
4. If configuring via configKey only, use the keyed lookup (clients().get(...)) rather than getClient()

Example fix

// before
public interface MyClient { ... } // no annotation
RestClientConfig cfg = restClientsConfig.getClient(MyClient.class); // throws
// after
@RegisterRestClient(configKey = "my-client")
public interface MyClient { ... }
RestClientConfig cfg = restClientsConfig.getClient(MyClient.class);

if (!RestClientKeysProvider.KEYS.contains(iface.getName()))
    throw new IllegalArgumentException("REST client not registered: " + iface.getName() + " — missing @RegisterRestClient?");

try { RestClientConfig cfg = config.getClient(iface); } catch (IllegalArgumentException e) { log.error("Client not registered: {}", e.getMessage()); }

When it happens

Trigger: Injecting/looking up RestClientConfig (or calling config.getClient(SomeInterface.class)) for an interface that lacks @RegisterRestClient, so its name is absent from RestClientKeysProvider.KEYS; also happens when the build-time registration was skipped (wrong package not scanned, annotation processor not applied) or when the class name differs between build and runtime (relocation/shading).

Common situations: Forgetting @RegisterRestClient on the interface; referencing the client config by a class from a different module that is not part of the Quarkus app's index; using the programmatic config API for a client configured only via configKey without registration; typos producing a different FQCN than the registered one.

Related errors

• Token exchange is required but OIDC client is configured to
• Failed to instantiate the HTTP client options " + httpClient
• No URL specified. Cannot build a rest client without URL
• Failed to load application configuration
• Failed to initialize application configuration

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