quarkusio/quarkus · error · IllegalArgumentException

Authentication mechanism must not be null or blank

Error message

Authentication mechanism must not be null or blank

What it means

Thrown by HttpPermission.authenticatedWith(String) when the given mechanism name is null or blank. The string is used as the authentication mechanism identifier, so an empty value would produce an unusable policy; the builder rejects it immediately with IllegalArgumentException.

Source

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

            return authenticatedWith("webauthn");
        }

        @Override
        public HttpPermission authorizationCodeFlow() {
            return authenticatedWith("code");
        }

        @Override
        public HttpSecurity authenticated() {
            return authorization().authenticated();
        }

        @Override
        public HttpPermission authenticatedWith(String mechanism) {
            validateAuthenticationNotSetYet();
            requireAuthenticationByDefault();
            if (mechanism == null || mechanism.isBlank()) {
                throw new IllegalArgumentException("Authentication mechanism must not be null or blank");
            }
            this.authMechanism = new HttpSecurityConfiguration.AuthenticationMechanisms(mechanism);
            return this;
        }

        @Override
        public HttpPermission authenticatedWith(Set<String> schemes) {
            validateAuthenticationNotSetYet();
            requireAuthenticationByDefault();
            if (schemes == null || schemes.isEmpty()) {
                throw new IllegalArgumentException("Authentication mechanism must not be null or emptz");
            }
            this.authMechanism = HttpSecurityConfiguration.AuthenticationMechanisms.from(schemes);
            return this;
        }

        @Override
        public HttpPermission shared() {

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass a valid, non-blank mechanism name (e.g. BasicAuthentication.AUTH_MECHANISM_SCHEME or a registered named mechanism).
2. Validate/trim the value before the call; fail early if a config-derived value is missing.
3. Use a dedicated convenience method (basic(), form(), bearer(), ...) instead of hand-built strings.

Example fix

// before
String mech = config.getValue("auth.mechanism"); // may be null
httpSecurity.paths("/api/*").authenticatedWith(mech); // throws
// after
if (mech != null && !mech.isBlank()) {
    httpSecurity.paths("/api/*").authenticatedWith(mech);
}

if (mechanism == null || mechanism.isBlank()) throw new IllegalArgumentException("mechanism required");

static boolean isValidMechanism(String m) { return m != null && !m.isBlank(); }

try { perm.authenticatedWith(mechanism); } catch (IllegalArgumentException e) { if (!e.getMessage().contains("must not be null or blank")) throw e; }

When it happens

Trigger: Passing a null or "" mechanism name to authenticatedWith, or via wrappers basic()/form()/bearer()/webAuthn()/authorizationCodeFlow() built from a null/blank constant or config value.

Common situations: Reading the mechanism name from a config property or environment variable that is unset; typos yielding an empty string after trimming; dynamically built names from string concatenation.

Understand the failure class

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

Related errors

• Source role must not be null
• Target roles for role '%s' must not be null
• Target role for role '%s' must not be null
• Role to roles mapping must not be null
• HttpSecurityPolicy must not be null

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