MongoParseError: Invalid scheme, expected connection string to start with "mongodb://" or "mongodb+srv://"

By Ohad Krispin, founder of VibeRaven · LinkedIn

"MongoParseError: Invalid scheme, expected connection string to start with "mongodb://" or "mongodb+srv://"" means the string given to MongoClient does not begin with either prefix. The check runs in the constructor, before any network call, so the password and the Atlas IP access list are not involved. On Vercel the value is usually not what you pasted: it is empty, or it carries quote marks, a space at the start, a MONGODB_URI= prefix or just a host and port. A variable that is not set at all fails differently, with TypeError: Cannot read properties of undefined (reading 'startsWith'). Re-enter the value with no quotes, for Production and Preview, and redeploy. Reproduced with mongodb 7.8.0 on 2026-10-31.

What does each bad value print?

The message comes from the ConnectionString constructor in the mongodb-connection-string-url package, which the driver uses (src/index.ts). On 2026-10-31, new MongoClient(value) with mongodb 7.8.0 threw the parse error for all of these values, and threw the TypeError for undefined.

undefined                          TypeError: Cannot read properties of undefined (reading 'startsWith')
""                                 MongoParseError: Invalid scheme, expected connection string to start with ...
"mongodb+srv://u:p@c.example.net/db"   (quote marks inside the value)   MongoParseError
'mongodb://localhost/db'             (single quotes inside the value)  MongoParseError
" mongodb://localhost/db"           (space at start)                  MongoParseError
MONGODB_URI=mongodb://localhost/db (name= copied into the value)    MongoParseError
localhost:27017                    (no scheme)                       MongoParseError

Why does it work locally?

Next.js loads .env* files into process.env, and its docs show values wrapped in double quotes in a .env file, so the file parser treats the quotes as quoting. A value typed into the Vercel Value field is not read by that parser, and I found no Vercel doc saying the field strips quotes. Enter the bare string. A variable that only exists in .env.local is also missing on Vercel: create-next-app adds all .env files to .gitignore, so the file is never deployed. Vercel applies variables per environment and only to new deployments.

What does Mongoose print instead?

mongoose.connect() with a quoted or empty string throws the same MongoParseError. With undefined, mongoose 9.11.4 throws a MongooseError first: the uri parameter to openUri() must be a string, got "undefined". Mongoose's Next.js guide has its dbConnect() throw "Please define the MONGODB_URI environment variable" when the variable is missing, and the official Next.js with-mongodb example throws a similar guard, Invalid/Missing environment variable: "MONGODB_URI", at module load.

MongooseError: The uri parameter to openUri() must be a string, got "undefined". Make sure the first parameter to mongoose.connect() or mongoose.createConnection() is a string.

Checklist

How to fix it, then check the fix

01
Log the first 14 characters of the value in the failing route. A correct value prints the whole scheme, and a bad one shows a quote, a space or undefined:
```
console.log(JSON.stringify(process.env.MONGODB_URI?.slice(0, 14)));
// "mongodb+srv://"  or  "\"mongodb+srv:/"  or  undefined
```
02In the Vercel project's Environment Variables settings, delete MONGODB_URI and add it again as the bare string from Atlas, with no quotes, no MONGODB_URI= prefix and no spaces, for Production and Preview. If you installed the Atlas integration from the Vercel Marketplace, it sets MONGODB_URI for you.
03Make sure the name in the code matches the name in Vercel exactly, and that the environment you are testing (Production or Preview) has it.

Add a guard so the next miss names the variable. This mirrors the official Next.js with-mongodb example:

const uri = process.env.MONGODB_URI;
if (!uri) {
  throw new Error('Invalid/Missing environment variable: "MONGODB_URI"');
}

05Add MONGODB_URI= with no value to .env.example so the name is documented. Redeploy, because Vercel applies changed variables only to new deployments, then call the route: it no longer throws MongoParseError.

Sources

Official docs behind this checklist

More Vercel errors · More MongoDB errors

Browse all launch guides · Read resources · How to make and check your next change

FAQ

FAQ for builders before launch

Does this error mean my password or IP is wrong?

No. MongoClient throws it in the constructor, before it opens any connection. If the string parses and you then see a timeout, that is a different problem: the Atlas IP access list or the cluster state.

Should I use mongodb+srv:// or mongodb://?

Both are accepted. MongoDB says the mongodb+srv:// prefix simplifies connecting to a cluster, and the mongodb:// prefix is the form that lists every member of a replica set or sharded cluster. Use the string Atlas shows you.

Does the Atlas integration on Vercel set the variable?

Yes. MongoDB says the Native Integration configures the MONGODB_URI environment variable, and Vercel says the variable scope matches the environments on the project connection. If the app reads another name, either rename the read or add that name yourself.