quarkusio/quarkus · error · IllegalArgumentException

Cannot configure form-based authentication programmatically

Error message

Cannot configure form-based authentication programmatically because it has already been configured in the 'application.properties' file

What it means

When a FormAuthenticationMechanism is registered programmatically via HttpSecurity.mechanism(), Quarkus compares the form auth config in application.properties against the defaults. If any quarkus.http.auth.form.* property was customized, the configuration is considered already owned by the properties file and merging/overriding programmatically is disallowed, so an IllegalArgumentException is thrown. This keeps a single source of truth for form-based auth configuration.

Source

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

    }

    @Override
    public HttpSecurity csrf(CSRF csrf) {
        if (csrf == null) {
            throw new IllegalArgumentException("CSRF must not be null");
        }
        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");
            }

View on GitHub (pinned to e1c734241f)

Solutions

Remove or reset all quarkus.http.auth.form.* properties from application.properties so the programmatic config is the sole source.
Configure form authentication exclusively in application.properties and drop the programmatic mechanism() call.
If both are needed, move the properties values into the programmatic FormAuthenticationMechanism configuration instead.

Example fix

// before (application.properties)
quarkus.http.auth.form.landing-page=/index.html
// code: httpSecurity.mechanism(new FormAuthenticationMechanism(...)) // throws
// after: remove the landing-page property, or drop the programmatic registration
httpSecurity.mechanism(new FormAuthenticationMechanism(...));

Defensive patterns

Strategy: validation

Validate before calling

// before registering form auth programmatically, ensure no form properties are set
// ConfigProvider.getConfig().getOptionalValue("quarkus.http.auth.form.enabled", Boolean.class)
//     .ifPresent(v -> { throw new IllegalStateException("Form auth already configured via properties"); });
httpSecurity.mechanism(new FormAuthenticationMechanism(...));

Try / catch

try {
    httpSecurity.mechanism(formMechanism);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("form-based authentication")) {
        log.warn("Form auth already configured in application.properties; skipping programmatic registration");
    } else {
        throw e;
    }
}

Prevention

Pick one source of truth (properties OR code) for form authentication per application.
Grep application.properties for quarkus.http.auth.form.* before adding programmatic form auth.
Inherited/shared property files often carry stale form settings — audit them during migration.

When it happens

Trigger: Calling httpSecurity.mechanism(new FormAuthenticationMechanism(...)) (or any API that routes through mechanism()) while application.properties contains non-default quarkus.http.auth.form.* settings (e.g. quarkus.http.auth.form.enabled, landing-page, post-location, cookie parameters).

Common situations: Applications that originally configured form auth via application.properties and later add programmatic security setup; copied config files that still carry form properties; following docs examples that register form auth in code while an old properties entry remains.

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/37bb25449ef491d0. Report an issue: GitHub.