quarkusio/quarkus · error · IllegalStateException

Neither baseUri nor baseUrl was specified

Error message

Neither baseUri nor baseUrl was specified

What it means

Thrown by QuarkusRestClientBuilder.build when neither baseUri nor baseUrl was set on the builder. A REST client cannot make requests without a target base URI, so build fails fast with IllegalStateException.

Source

Thrown at extensions/resteasy-classic/resteasy-client/runtime/src/main/java/io/quarkus/restclient/runtime/QuarkusRestClientBuilder.java:261

    @Override
    public RestClientBuilder executorService(ExecutorService executor) {
        if (executor == null) {
            throw new IllegalArgumentException("ExecutorService must not be null");
        }
        executorService = ContextualExecutors.wrap(executor);
        return this;
    }

    public <T> T build(Class<T> aClass, ClientHttpEngine httpEngine)
            throws IllegalStateException, RestClientDefinitionException {

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

        // Interface validity
        verifyInterface(aClass);

        if (baseURI == null) {
            throw new IllegalStateException("Neither baseUri nor baseUrl was specified");
        }

        // Provider annotations
        RegisterProvider[] providers = aClass.getAnnotationsByType(RegisterProvider.class);

        for (RegisterProvider provider : providers) {
            register(provider.value(), provider.priority());
        }

        // Default exception mapper
        if (!isMapperDisabled()) {
            register(DefaultResponseExceptionMapper.class);
        }

        builderDelegate.register(new ExceptionMapping(localProviderInstances), 1);

        ClassLoader classLoader = aClass.getClassLoader();

View on GitHub (pinned to e1c734241f)

Solutions

1. Call builder.baseUri(URI.create("https://host")) or baseUrl(URL) before build()
2. Set quarkus.rest-client.<config-key>.url (or quarkus.rest-client.<fqcn>.url) in application.properties
3. Check that the active config profile actually defines the URL property
4. Verify the @RegisterRestClient configKey matches the property prefix exactly

Example fix

// before
MyClient c = RestClientBuilder.newBuilder().build(MyClient.class); // IllegalStateException
// after
MyClient c = RestClientBuilder.newBuilder()
        .baseUri(URI.create("https://api.example.com"))
        .build(MyClient.class);

if (baseUri == null && baseUrl == null) {
    throw new IllegalStateException("Set quarkus.rest-client.<key>.url or call baseUri()/baseUrl() before build()");
}

try {
    client = builder.build(MyClient.class);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Neither baseUri nor baseUrl was specified")) {
        throw new ConfigurationException("Missing quarkus.rest-client.<key>.url", e);
    }
    throw e;
}

When it happens

Trigger: Calling build(Class) without calling baseUri(...) or baseUrl(...) first; config property quarkus.rest-client.<key>.url missing; baseUri set conditionally and the condition never hit.

Common situations: Forgetting quarkus.rest-client.<config-key>.url in application.properties; profile-specific config (e.g. %prod) missing the URL; constructing the builder manually in tests and skipping baseUri; key name mismatch between @RegisterRestClient(configKey=...) and the property prefix.

Related errors

• quarkus.rest.client.multipart-buffer-size cannot be lower th
• Build time property cannot be changed at runtime: ${mismatch
• Token exchange is required but OIDC client is configured to
• Proxy type HTTP is required
• Unable to lookup configuration for REST Client ${restClientI

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