quarkusio/quarkus · error · IllegalArgumentException

Unsupported authentication mechanism

Error message

Unsupported authentication mechanism 

What it means

After mapping the configured mechanism name to a driver AuthenticationMechanism, Quarkus only supports SCRAM-SHA-1, SCRAM-SHA-256, MONGODB-AWS, GSSAPI, MONGODB-X509 (handled above) and the default null. Any other mapped mechanism value reaches this fall-through and throws IllegalArgumentException.

Source

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

        String username = usernamePassword.username();
        char[] password = usernamePassword.password();
        MongoCredential credential;
        if (mechanism == GSSAPI) {
            credential = MongoCredential.createGSSAPICredential(username);
        } else if (mechanism == PLAIN) {
            credential = MongoCredential.createPlainCredential(username, authSource, password);
        } else if (mechanism == MONGODB_X509) {
            credential = MongoCredential.createMongoX509Credential(username);
        } else if (mechanism == SCRAM_SHA_1) {
            credential = MongoCredential.createScramSha1Credential(username, authSource, password);
        } else if (mechanism == SCRAM_SHA_256) {
            credential = MongoCredential.createScramSha256Credential(username, authSource, password);
        } else if (mechanism == MONGODB_AWS) {
            credential = MongoCredential.createAwsCredential(username, password);
        } else if (mechanism == null) {
            credential = MongoCredential.createCredential(username, authSource, password);
        } else {
            throw new IllegalArgumentException("Unsupported authentication mechanism " + mechanism);
        }

        //add the properties
        if (!config.credentials().authMechanismProperties().isEmpty()) {
            for (Map.Entry<String, String> entry : config.credentials().authMechanismProperties().entrySet()) {
                credential = credential.withMechanismProperty(entry.getKey(), entry.getValue());
            }
        }

        return credential;
    }

    private UsernamePassword determineUserNamePassword(CredentialConfig config) {
        if (config.credentialsProvider().isPresent()) {
            String beanName = config.credentialsProviderName().orElse(null);
            CredentialsProvider credentialsProvider = CredentialsProviderFinder.find(beanName);
            String name = config.credentialsProvider().get();
            Map<String, String> credentials = credentialsProvider.getCredentialsAsync(name).await().indefinitely();

View on GitHub (pinned to e1c734241f)

Solutions

1. Use SCRAM-SHA-256 (default for MongoDB 4.0+) or SCRAM-SHA-1: set auth-mechanism=SCRAM-SHA-256
2. For AWS IAM auth use MONGODB-AWS with session credentials
3. For LDAP use a supported path or connect via a driver-supported mechanism not requiring Quarkus's credential branch; remove unsupported auth-mechanism and let the driver default (null branch) negotiate
4. Verify the exact mechanism value against the configured MongoDB server version

Example fix

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

Set<String> supported = Set.of("SCRAM-SHA-1", "SCRAM-SHA-256", "MONGODB-X509", "GSSAPI", "MONGODB-AWS");
String mech = config.credentials().authMechanism();
if (mech != null && !supported.contains(mech.toUpperCase())) {
    throw new ConfigurationException("auth-mechanism must be one of " + supported + ", got: " + mech);
}

When it happens

Trigger: `quarkus.mongodb.credentials.auth-mechanism` set to a value that maps to a mechanism the Quarkus wiring does not handle (e.g. PLAIN, MONGODB-CR) rather than one of the supported branches.

Common situations: Legacy MONGODB-CR deployments using old config values; PLAIN (LDAP) authentication copied from old driver examples; typos that still resolve via fromMechanismName but aren't wired by Quarkus.

Understand the failure class

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

Related errors

• Invalid authMechanism '
• You must provide either a valid username/password pair for B
• Config property 'quarkus.mongodb.database' must be defined w
• <errorMessage>.formatted(clientName) (required Liquibase Mon
• Mongo client named '%s' not found

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