quarkusio/quarkus · error · ConfigurationException

Either 'quarkus.oidc-client.auth-server-url' or absolute 'qu

Error message

Either 'quarkus.oidc-client.auth-server-url' or absolute 'quarkus.oidc-client.token-path' URL must be set

What it means

At build/record time OidcClientRecorder.createOidcClientUni validates that the client can locate a token endpoint: either quarkus.oidc-client.auth-server-url is set (so the token path can be derived/discovered) or token-path is an absolute URL. Otherwise a ConfigurationException is recorded and the client is marked uninitialized, failing at first use.

Source

Thrown at extensions/oidc-client/runtime/src/main/java/io/quarkus/oidc/client/runtime/OidcClientRecorder.java:101

    }

    protected static Uni<OidcClient> createOidcClientUni(OidcClientConfig oidcConfig, String oidcClientId,
            Vertx vertx, OidcTlsSupport tlsSupport, ProxyConfigurationRegistry proxyConfigurationRegistry) {
        if (!oidcConfig.clientEnabled()) {
            String message = String.format("'%s' client configuration is disabled", oidcClientId);
            LOG.debug(message);
            return Uni.createFrom().item(new DisabledOidcClient(message));
        }
        if (oidcConfig.id().isEmpty()) {
            // if user did not set the client id
            // we do set 'id' to the named client key
            // e.g. quarkus.oidc-client.<<name>>.id=<<name>>
            return Uni.createFrom().failure(new IllegalStateException("OIDC Client ID must be set"));
        }

        try {
            if (oidcConfig.authServerUrl().isEmpty() && !OidcCommonUtils.isAbsoluteUrl(oidcConfig.tokenPath())) {
                throw new ConfigurationException(
                        "Either 'quarkus.oidc-client.auth-server-url' or absolute 'quarkus.oidc-client.token-path' URL must be set");
            }
            OidcCommonUtils.verifyEndpointUrl(getEndpointUrl(oidcConfig));
        } catch (Throwable t) {
            LOG.debug(t.getMessage());
            String message = String.format("'%s' client configuration is not initialized", oidcClientId);
            return Uni.createFrom().item(new DisabledOidcClient(message));
        }

        try {
            OidcCommonUtils.verifyCommonConfiguration(oidcConfig, false, false);
            OidcCommonUtils.validateCredentialsForAllEndpoints(oidcConfig.credentials());
        } catch (ConfigurationException e) {
            return Uni.createFrom().failure(e);
        }

        var mutinyVertx = new io.vertx.mutiny.core.Vertx(vertx);
        OidcWebClient client = OidcWebClient.create(oidcConfig, tlsSupport, mutinyVertx, proxyConfigurationRegistry,

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.oidc-client.auth-server-url (or quarkus.oidc-client.<name>.auth-server-url for named clients)
Or set an absolute quarkus.oidc-client.token-path URL
Check the exact config key/named-client name matches the @OidcClient annotation value
Verify active config profile includes these properties

Example fix

# before
# quarkus.oidc-client."my-client".auth-server-url missing

# after
quarkus.oidc-client."my-client".auth-server-url=http://localhost:8180/realms/test

Defensive patterns

Strategy: validation

Validate before calling

if (config.authServerUrl().isEmpty() && !isAbsoluteUrl(config.tokenPath())) {
    throw new IllegalArgumentException("Set quarkus.oidc-client.auth-server-url or absolute token-path");
}

Type guard

boolean isClientUrlConfigured(OidcClientConfig c) {
    return c.authServerUrl().isPresent() || isAbsoluteUrl(c.tokenPath());
}

Try / catch

try { return oidcClient.getTokens().await().indefinitely(); } catch (RuntimeException e) { if (e.getMessage() != null && e.getMessage().contains("client configuration is not initialized")) { throw new IllegalStateException("Check quarkus.oidc-client.auth-server-url / token-path", e); } throw e; }

Prevention

Add a startup assertion that all named clients have auth-server-url
Keep named-client config keys matching @OidcClient values exactly
Check per-profile config (e.g. %prod.) coverage

When it happens

Trigger: Producing an OIDC client bean with neither quarkus.oidc-client.auth-server-url nor an absolute quarkus.oidc-client.token-path configured — typical for named clients (quarkus.oidc-client.<name>.auth-server-url) whose config block is missing.

Common situations: Adding a named OIDC client via @OidcClient("name") without the corresponding quarkus.oidc-client."name".auth-server-url property; typos in the config key; running in a profile that drops the config block.

Related errors

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