quarkusio/quarkus · error · IllegalStateException

No URL specified. Cannot build a rest client without URL

Error message

No URL specified. Cannot build a rest client without URL

What it means

The MP REST Client spec requires a base URI/URL before a client can be built. After applying all overrides (property overrides like quarkus.rest-client.<key>.url and the builder's baseUri/baseUrl), if no URI is present, build throws this IllegalStateException. It is the spec-mandated behavior for a missing endpoint.

Source

Thrown at extensions/resteasy-reactive/rest-client/runtime/src/main/java/io/quarkus/rest/client/reactive/runtime/RestClientBuilderImpl.java:518

        ArcContainer arcContainer = Arc.container();
        if (arcContainer == null) {
            throw new IllegalStateException(
                    "The Reactive REST Client needs to be built within the context of a Quarkus application with a valid ArC (CDI) context running.");
        }

        SmallRyeConfig config = ConfigProvider.getConfig().unwrap(SmallRyeConfig.class);
        RestClientsConfig restClients = config.getConfigMapping(RestClientsConfig.class);

        // support overriding the URI from the override-uri property
        var overrideUrlKeyName = String.format("quarkus.rest-client.\"%s\".override-uri", aClass.getName());
        Optional<String> maybeOverrideUri = config.getOptionalValue(overrideUrlKeyName, String.class);
        if (maybeOverrideUri.isPresent()) {
            uri = URI.create(maybeOverrideUri.get());
        }

        if (uri == null) {
            // mandated by the spec
            throw new IllegalStateException("No URL specified. Cannot build a rest client without URL");
        }

        RestClientListeners.get().forEach(listener -> listener.onNewClient(aClass, this));

        AnnotationRegisteredProviders annotationRegisteredProviders = arcContainer
                .instance(AnnotationRegisteredProviders.class).get();
        for (Map.Entry<Class<?>, Integer> mapper : annotationRegisteredProviders.getProviders(aClass).entrySet()) {
            register(mapper.getKey(), mapper.getValue());
        }

        exceptionMappers.sort(Comparator.comparingInt(ResponseExceptionMapper::getPriority));
        redirectHandlers.sort(Comparator.comparingInt(RedirectHandler::getPriority));
        clientBuilder.register(new MicroProfileRestClientResponseFilter(exceptionMappers));
        clientBuilder.followRedirects(followRedirects != null ? followRedirects : restClients.followRedirects().orElse(false));

        RestClientsConfig.RestClientLoggingConfig configRootLogging = restClients.logging();

        LoggingScope effectiveLoggingScope = LoggingScope.NONE;

View on GitHub (pinned to e1c734241f)

Solutions

1. Set the URL in application.properties: quarkus.rest-client.<config-key>.url=http://host:port (or mp.rest-client... for MP config).
2. Call builder.baseUri(URI.create(...)) / baseUrl(...) explicitly when building programmatically.
3. Verify the config key matches the interface name or its @RegisterRestClient(configKey=...) value.
4. Check that the property is not disabled by the active Quarkus profile.

Example fix

// before
MyClient c = QuarkusRestClientBuilder.newBuilder().build(MyClient.class); // IllegalStateException

// after
MyClient c = QuarkusRestClientBuilder.newBuilder()
        .baseUri(URI.create("http://localhost:8080"))
        .build(MyClient.class);
// or in application.properties: quarkus.rest-client.my-client.url=http://localhost:8080

URI uri = ...resolve from config...;
if (uri == null || uri.toString().isBlank()) {
    throw new IllegalStateException("Set quarkus.rest-client.<key>.url before building the client");
}
builder.baseUri(uri).build(MyClient.class);

null

try {
    T client = builder.build(MyClient.class);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("No URL specified")) {
        builder.baseUri(URI.create(defaultUrl)).build(MyClient.class);
    } else throw e;
}

When it happens

Trigger: Building a client with no builder.baseUri(...)/baseUrl(...) call and no quarkus.rest-client.<config-key>.url property (nor the legacy MP property) configured.

Common situations: Missing @RegisterRestClient config in application.properties; config key mismatch between the interface's configKey and the property name; typos like 'uri' vs 'url'; profile-specific config not active in the test environment.

Related errors

• Token exchange is required but OIDC client is configured to
• Proxy configuration with name ${key} was requested but quark
• Unable to lookup configuration for REST Client ${restClientI
• Failed to instantiate the HTTP client options " + httpClient
• Unable to determine the proper baseUrl/baseUri. Consider reg

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