MongoServerError: Authentication failed

What it means

A MongoDB user belongs to one database: the one it was created in, called its authentication database. To sign in, the client names that database (the authSource option) and proves the password with SCRAM. The server checked and said no: code 18, AuthenticationFailed.

The message is the same whether the password is wrong or no user by that name exists in that database, so a stranger can’t learn which user names are real. The server log says which it was.

Common causes

1. The wrong authentication database. Without authSource, the client uses the database in the URL’s path, or admin if there isn’t one. A user created in admin (the Docker image’s MONGO_INITDB_ROOT_USERNAME user, and every password user on Atlas) fails when the URL ends in /myapp.
2. The wrong password: a typo, an old one, or a trailing newline from a secrets file.
3. Special characters in the URL that weren’t percent-encoded, so the client sent something else or couldn’t read the URL.
4. The user doesn’t exist on this server: a different host, port or cluster, or a Docker volume that already had data, so the image’s MONGO_INITDB_* variables were ignored.
5. A forced mechanism. authMechanism=SCRAM-SHA-256 for a user that only has SCRAM-SHA-1 credentials (or the reverse) fails with a different message and code 334, shown below.

How to fix it

Check what the server saw

The mongod log records each failure with the reason. For Docker:

docker logs <container> 2>&1 | grep 'Failed to authenticate'

The error field tells the causes apart (lines trimmed):

"user":"seo_mongo_app","db":"seo_mongo","error":"AuthenticationFailed: SCRAM authentication failed, storedKey mismatch"
"user":"seo_mongo_app","db":"admin","error":"UserNotFound: Could not find user \"seo_mongo_app\" for db \"admin\""

storedKey mismatch is a wrong password. UserNotFound means no such user in that database, which is usually the wrong authSource. On Atlas, use the project’s logs or check the user under Database Access.

Set authSource

Name the database the user was created in:

mongodb://<user>:<password>@<host>:27017/<app database>?authSource=admin

In mongosh the flag is --authenticationDatabase admin. To find where a user lives, connect as an administrator and run:

db.getSiblingDB("admin").system.users.find({ user: "<user>" }, { _id: 0, user: 1, db: 1 })

Reset the password

As an administrator, in the user’s authentication database:

db.getSiblingDB("admin").changeUserPassword("<user>", passwordPrompt())

passwordPrompt() asks for the password without echoing it or saving it in your shell history. Atlas users are managed in the Atlas UI, CLI or API, not with shell commands; Atlas rolls back changes made any other way.

Encode special characters in URLs

In a connection string, $ : / ? # [ ] @ in the user name or password must be percent-encoded: p@ss:word/1 becomes p%40ss%3Aword%2F1. See special characters in passwords. Command-line flags (-u, -p) take the password as it is.

Don’t force a mechanism

Remove authMechanism from the URL unless you need it: the client tries SCRAM-SHA-256 and falls back to SCRAM-SHA-1. To give an old user credentials for both, set its password again with both mechanisms:

db.getSiblingDB("admin").updateUser("<user>", {
  pwd: passwordPrompt(),
  mechanisms: ["SCRAM-SHA-1", "SCRAM-SHA-256"]
})

Reproduce it

MongoDB 8.0.32 in Docker, mongosh 2.12.0. A user seo_mongo_app created in the seo_mongo database, with a wrong password:

mongosh 'mongodb://seo_mongo_app:wrong@localhost:27017/seo_mongo'

MongoServerError: Authentication failed.

The same message came for the right password with ?authSource=admin, for the right password with no database in the path (so authSource was admin), and for a user that doesn’t exist. A user created in admin with the right password also failed with a URL ending in /seo_mongo, and signed in once ?authSource=admin was added. The error’s code was 18 and its codeName AuthenticationFailed.

A password p@ss:word/1 put in the URL unencoded:

MongoRuntimeError: Unable to parse ss:word with URL

Percent-encoded as p%40ss%3Aword%2F1, it signed in. A user with only SCRAM-SHA-1 credentials and authMechanism=SCRAM-SHA-256 in the URL:

MongoServerError: Unable to use SCRAM-SHA-256 based authentication for user without any SCRAM-SHA-256 credentials registered

That one is code 334, MechanismUnavailable. Without authMechanism the same user signed in, and after the updateUser above it also worked with SCRAM-SHA-256.

In Inlet

Paste the connection URL (mongodb:// or mongodb+srv://) and Inlet fills the connection form. If the server rejects the password, the connection window shows the server’s message, asks for the password there and can save it in the Keychain. If you’re sure the password is right, check the authentication database (authSource) in the URL.