MONGODB PASSWORD URL ENCODING

NestJS Backend API for GoGrab Space platform - Architecture, Best Practices, and Common Issues

🔐 MongoDB Password URL Encoding Reference

Date: November 18, 2025
Issue: Special characters in MongoDB passwords must be URL-encoded

🔒 Security Notice

NEVER expose real credentials in documentation or code!

Your MongoDB connection string should be stored in:

File: .env.local (gitignored - NEVER committed)
Variable: MONGODB_CONNECTION_STRING

To get your credentials:

Log into MongoDB Atlas
Go to Database > Connect > Drivers
Copy your connection string
URL-encode any special characters in your password (see below)

📋 Common URL Encoding Reference

Character	URL Encoded	Example
`!`	`%21`	`pass!` → `pass%21`
`@`	`%40`	`pass@` → `pass%40`
`#`	`%23`	`pass#` → `pass%23`
`$`	`%24`	`pass$` → `pass%24`
`%`	`%25`	`pass%` → `pass%25`
`^`	`%5E`	`pass^` → `pass%5E`
`&`	`%26`	`pass&` → `pass%26`
`*`	`%2A`	`pass*` → `pass%2A`
`(`	`%28`	`pass(` → `pass%28`
`)`	`%29`	`pass)` → `pass%29`
`+`	`%2B`	`pass+` → `pass%2B`
`=`	`%3D`	`pass=` → `pass%3D`
`/`	`%2F`	`pass/` → `pass%2F`
`?`	`%3F`	`pass?` → `pass%3F`
`space`	`%20`	`my pass` → `my%20pass`

🔧 Quick Encoding Tool

Online Tools:

Command Line:

# Node.js - encode your password
node -e "console.log(encodeURIComponent('YOUR_PASSWORD_HERE'))"

# Python
python3 -c "import urllib.parse; print(urllib.parse.quote('YOUR_PASSWORD_HERE'))"

Example: If your password is myPass!@#:

node -e "console.log(encodeURIComponent('myPass!@#'))"
# Output: myPass%21%40%23

✅ Correct vs Incorrect

❌ WRONG (causes "bad auth" error):

# Raw special chars in password - WILL FAIL
MONGODB_CONNECTION_STRING=mongodb+srv://user:myPass!@@cluster.mongodb.net/
                                               ^^
                                         Raw special chars

✅ CORRECT:

# Special chars URL-encoded - WORKS
MONGODB_CONNECTION_STRING=mongodb+srv://user:myPass%21%[email protected]/
                                               ^^^^^^^
                                         URL-encoded: ! → %21, @ → %40

🚨 Common Mistakes

Mistake 1: Forgetting to encode

❌ password!@#
✅ password%21%40%23

Mistake 2: Double encoding

❌ password%2521%2540  (encoding the % itself)
✅ password%21%40

Mistake 3: Encoding the entire connection string

❌ mongodb%3A%2F%2Fuser%3A...  (encoding the protocol)
✅ mongodb://user:password%21@...  (only encode password)

📖 MongoDB Documentation

From MongoDB Connection String Docs:

Special characters in the connection string password must be percent encoded.

The username and password should be percent-encoded if they contain special characters.

🎯 Your Complete Configuration

File: .env.local (create in project root, NEVER commit to git)

# MongoDB Connection
# 1. Get your connection string from MongoDB Atlas
# 2. URL-encode any special characters in your password
# 3. Replace the placeholders below with your actual values
MONGODB_CONNECTION_STRING=mongodb+srv://<USERNAME>:<URL_ENCODED_PASSWORD>@<CLUSTER>.mongodb.net/?retryWrites=true&w=majority
MONGODB_DATABASE=<YOUR_DATABASE_NAME>

# JWT Secret (generate a secure random string)
JWT_SECRET=<YOUR_SECRET_KEY>

# Server Port
PORT=3000

# Node Environment
NODE_ENV=development

# CORS Origins
ALLOWED_ORIGINS=http://localhost:5200,http://localhost:5701,http://localhost:4200,http://localhost:5300

✅ Verification

After updating .env.local:

Restart backend: yarn serve:backend-only
Look for: MongoDB connected successfully
No more: MongoServerError: bad auth

Status: Reference guide for URL encoding MongoDB passwords