Atlas auth fails only for passwords with special characters

TL;DR: A password containing @, /, or : breaks URI parsing and looks like wrong credentials. URL-encode just the password. Confirm Look at the password. Fix URL-encode only the password before substituting it into the string: p@ss/w:rd becomes p%40ss%2Fw%3Ard.

The error

the user and password are definitely right (you just created them), but auth fails with `bad auth : Authentication failed`. The password contains `@`, `/`, `:`, `?`, `#`, or `%`.

The fix

Auth fails with special-character passwords

Symptom: the user and password are definitely right (you just created them), but auth fails with bad auth : Authentication failed. The password contains @, /, :, ?, #, or %.

Confirm

Look at the password. If it contains any URI-reserved character, the driver parses the connection string wrong: @ ends the user-info section early, / starts a new path segment, : splits user from password in the wrong place. The server then receives a mangled password.

Fix

URL-encode only the password before substituting it into the string:

const uri = template.replace('[password]', encodeURIComponent(password));

p@ss/w:rd becomes p%40ss%2Fw%3Ard. Never encode the whole URI; that breaks the scheme and hosts.

Verify

Connect with the encoded string. Then, to stop this class of bug forever, generate future passwords from a URI-safe alphabet (letters and digits plus a few safe symbols like - and _).

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Atlas auth fails only for passwords with special characters.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Atlas behavior.

Also seen as

• bad auth : Authentication failed
• `.

Confirm

Look at the password. If it contains any URI-reserved character, the driver parses the connection string wrong:`

URI encoding requirements for connection string credentials per https://www.mongodb.com/docs/manual/reference/connection-string/; auth failure troubleshooting per https://www.mongodb.com/docs/atlas/troubleshoot-connection/, verified 2026-09-26.