MongoParseError: Password contains unescaped characters MongoDB Origin: Data OSI layer 7 · Application Last updated 5 Nov 2026

MongoParseError: URI malformed, cannot be parsed / Password contains unescaped characters

The connection string contains characters in the user or password that must be percent-encoded.

Exact message you may see MongoParseError: URI malformed, cannot be parsedPassword contains unescaped charactersMongoParseError: Username contains unescaped charactersMongoAPIError: URI must include hostname, domain name, and tldURI malformed MongoDB password special characters
Explore the map of this error Full error map →
Seen on: MongoDB Node.js

Meaning

Characters : / ? # [ ] @ % in credentials must be URL-encoded (@ → %40, / → %2F). Build the URI with encodeURIComponent. The same applies to database names with special characters. Atlas users with passwords generated using symbols hit this frequently.

Common causes

  • @ or / inside the password
  • Unencoded #, ?, %
  • Copy-pasted connection string with <password> placeholder left in
  • Spaces in credentials
  • Missing mongodb:// prefix

⚡ Quick fix

  1. encodeURIComponent(password) when building the URI
  2. Replace <password> placeholder with the real encoded password
  3. Use the driver's options object (auth: {username, password})

Detailed fix by platform

Node.js

  1. const uri = \mongodb+srv://${encodeURIComponent(u)}:${encodeURIComponent(p)}@cluster0.abcde.mongodb.net/db\;

How to diagnose

  1. Password — Special chars encoded?
  2. Placeholder — Replaced?
  3. Scheme — Correct?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Data. Errors that are often confused with or caused by this one (click to open):

Atlas: bad auth: Authentication failed — MongoServerError: bad auth : Authentication failed. (Atlas user / special characters in password) (MongoDB)Atlas: bad auth: Auth…BSONObj size is invalid / exceeds maximum document size (16MB) — MongoServerError: BSONObj size: 17825792 (0x1100000) is invalid. Size must be between 0 and 16793600(16MB) (MongoDB)BSONObj size is inval…Can't connect from another host (bindIp 127.0.0.1) — MongoDB: connection refused / timed out from a remote host — mongod bindIp defaults to 127.0.0.1 (MongoDB)Can't connect from an…MongoDB Atlas: connection timed out — IP not whitelisted — MongoServerSelectionError: Could not connect to any servers in your MongoDB Atlas cluster. One common reason is that you're trying to access the database from an IP that isn't whitelisted (MongoDB)MongoDB Atlas: connec…MongoParseError — MongoDB: MongoParseError: Invalid scheme, expected connection string to start with "mongodb://" or "mongodb+srv://" (MongoDB)MongoParseErrorquerySrv ENOTFOUND _mongodb._tcp — MongoDB Atlas: Error: querySrv ENOTFOUND _mongodb._tcp.cluster0.abcde.mongodb.net (MongoDB)querySrv ENOTFOUND _m…Sort/Group exceeded memory limit of 100 MB (allowDiskUse) — MongoServerError: Exceeded memory limit for $group, but didn't allow external sort. Pass allowDiskUse:true to opt in (MongoDB)Sort/Group exceeded m…The uri parameter to openUri() must be a string, got "undefined" — MongooseError: The `uri` parameter to `openUri()` must be a string, got "undefined". Make sure the first parameter to `mongoose.connect()` is a string (MongoDB)The uri parameter to …MongoPars…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.