quarkusio/quarkus · error · IllegalArgumentException

Cannot configure basic authentication programmatically becau

Error message

Cannot configure basic authentication programmatically because the authentication realm has already been configured in the 'application.properties' file

What it means

BasicAuthenticationMechanism registered programmatically conflicts with a realm already set via the quarkus.http.auth.realm (or related auth realm) property. Quarkus refuses to merge: when the realm is present in application.properties, programmatic basic auth configuration throws an IllegalArgumentException. This guarantees the realm identity is unambiguous.

Source

Thrown at extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/HttpSecurityImpl.java:129

        }
        this.csrf = csrf;
        return this;
    }

    @Override
    public HttpSecurity mechanism(HttpAuthenticationMechanism mechanism) {
        Objects.requireNonNull(mechanism);
        if (mechanism.getClass() == FormAuthenticationMechanism.class) {
            final FormAuthConfig defaults = HttpSecurityUtils.getDefaultAuthConfig().auth().form();
            final FormAuthConfig actualConfig = vertxHttpConfig.auth().form();
            if (!actualConfig.equals(defaults)) {
                throw new IllegalArgumentException("Cannot configure form-based authentication programmatically "
                        + "because it has already been configured in the 'application.properties' file");
            }
        } else if (mechanism.getClass() == BasicAuthenticationMechanism.class) {
            String actualRealm = vertxHttpConfig.auth().realm().orElse(null);
            if (actualRealm != null) {
                throw new IllegalArgumentException("Cannot configure basic authentication programmatically because "
                        + "the authentication realm has already been configured in the 'application.properties' file");
            }
        } else if (mechanism.getClass() == MtlsAuthenticationMechanism.class) {
            boolean mTlsEnabled = !ClientAuth.NONE.equals(clientAuth);
            if (mTlsEnabled) {
                // current we do not allow "merging" (or overriding) of the configuration provided in application.properties
                // there shouldn't be a technical issue allowing that, but that's the behavior we have for other mechanisms
                // as well, so this method only allows to "enable" mTLS, never disable or change configuration provided
                // properties file
                throw new IllegalArgumentException("TLS client authentication has already been enabled with this API or"
                        + " with the 'quarkus.http.ssl.client-auth' configuration property");
            }
            var mTLS = ((MtlsAuthenticationMechanism) mechanism);
            clientAuth = mTLS.getTlsClientAuth();
            if (mTLS.getHttpServerTlsConfigName().isPresent()) {
                if (httpServerTlsConfigName.isPresent()) {
                    throw new IllegalArgumentException("Cannot configure TLS configuration name programmatically because it "
                            + " has already been configured with the 'quarkus.http.tls-configuration-name' configuration property");

View on GitHub (pinned to e1c734241f)

Solutions

Remove quarkus.http.auth.realm (and basic auth realm properties) from application.properties before registering basic auth in code.
Keep basic auth entirely in application.properties and remove the programmatic basic()/mechanism() call.
Align on one configuration source and delete the other.

Example fix

// before (application.properties)
quarkus.http.auth.realm=secure-realm
// code: httpSecurity.basic("secure-realm") // throws
// after: delete the realm property (or drop the programmatic call)
httpSecurity.basic("secure-realm");

Defensive patterns

Strategy: validation

Validate before calling

// ensure no realm is set in properties before programmatic basic auth
// ConfigProvider.getConfig().getOptionalValue("quarkus.http.auth.realm", String.class)
//     .ifPresent(r -> { throw new IllegalStateException("Realm already set in application.properties"); });
httpSecurity.basic("my-realm");

Try / catch

try {
    httpSecurity.basic(realm);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("basic authentication")) {
        log.warn("Realm already configured in application.properties; keeping properties-based config");
    } else {
        throw e;
    }
}

Prevention

Remove quarkus.http.auth.realm from application.properties when switching to programmatic basic auth.
Document in the team runbook whether basic auth lives in properties or code.
Check generated/included properties files (e.g. application.properties includes) for realm entries.

When it happens

Trigger: Calling httpSecurity.basic("my-realm") or httpSecurity.mechanism(new BasicAuthenticationMechanism(...)) while application.properties defines quarkus.http.auth.realm (or basic auth realm properties).

Common situations: Apps migrated from properties-based security to programmatic HttpSecurity while leaving quarkus.http.auth.realm in the properties file; inherited application.properties files where the realm was set long ago and forgotten.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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