quarkusio/quarkus · error · IllegalArgumentException

Invalid authMechanism '

Error message

Invalid authMechanism '

What it means

Quarkus converts the configured auth-mechanism string via AuthenticationMechanism.fromMechanismName(uppercased). If the name is not a recognized driver mechanism, the resulting IllegalArgumentException is rethrown with this clearer message.

Source

Thrown at extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/MongoClients.java:594

            String user = credentials.get(USER_PROPERTY_NAME);
            String password = credentials.get(PASSWORD_PROPERTY_NAME);
            return new UsernamePassword(user, password.toCharArray());
        } else {
            String username = config.username().orElse(null);
            if (username == null) {
                return null;
            }
            char[] password = config.password().map(String::toCharArray).orElse(null);
            return new UsernamePassword(username, password);
        }
    }

    private AuthenticationMechanism getAuthenticationMechanism(String authMechanism) {
        AuthenticationMechanism mechanism;
        try {
            mechanism = AuthenticationMechanism.fromMechanismName(authMechanism.toUpperCase());
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Invalid authMechanism '" + authMechanism + "'");
        }
        return mechanism;
    }

    @PreDestroy
    public void stop() {
        for (MongoClient client : mongoClients.values()) {
            if (client != null) {
                client.close();
            }
        }
        for (ReactiveMongoClient reactive : reactiveMongoClients.values()) {
            if (reactive != null) {
                reactive.close();
            }
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Use one of: SCRAM-SHA-1, SCRAM-SHA-256, MONGODB-X509, GSSAPI, MONGODB-AWS, PLAIN (only where supported)
2. Remove the auth-mechanism property entirely to let the driver negotiate the default mechanism
3. Check for whitespace/casing issues; Quarkus uppercases automatically so case itself is fine
4. Validate the property with a quick startup test after fixing

Example fix

// before
quarkus.mongodb.credentials.auth-mechanism=SCRAM-SHA258
// after
quarkus.mongodb.credentials.auth-mechanism=SCRAM-SHA-256

List<String> valid = AuthenticationMechanism.values().stream()
    .map(Enum::name).toList();
String mech = "SCRAM-SHA-256";
if (!valid.contains(mech.toUpperCase())) {
    throw new ConfigurationException("Invalid auth-mechanism: " + mech + "; valid: " + valid);
}

When it happens

Trigger: `quarkus.mongodb.credentials.auth-mechanism` set to a misspelled or non-existent name such as `scram-sha258`, `sha256`, or `mongodb-aws-iam`.

Common situations: Typos in application.properties; mixing driver enum names with Mongo URI style names; documentation from an older driver version using different casing/spelling.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Unsupported authentication mechanism
• Unrecognized dependency flag '<trimmed>'. Supported flags: O
• Parameter 'mode' was set to '<mode>' while expected one of '
• Parameter 'mode' was set to '<mode>' while expected one of '
• Parameter 'mode' was set to '<mode>' while expected one of '

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