{"record":{"id":"4715a38e00a0bbf2","repo":"Automattic/mongoose","slug":"the-uri-parameter-to-openuri-must-be-a-strin","errorCode":null,"errorMessage":"The `uri` parameter to `openUri()` must be a string, got \"${typeof uri}\". Make sure the first parameter to `mongoose.connect()` or `mongoose.createConnection()` is a string.","messagePattern":"The `uri` parameter to `openUri\\(\\)` must be a string, got \"(.+?)\"\\. Make sure the first parameter to `mongoose\\.connect\\(\\)` or `mongoose\\.createConnection\\(\\)` is a string\\.","errorType":"exception","errorClass":"MongooseError","httpStatus":null,"severity":"critical","filePath":"lib/drivers/node-mongodb-native/connection.js","lineNumber":234,"sourceCode":" * Implementation of `listDatabases()` for MongoDB driver\n *\n * @return {Promise}\n * @api public\n */\n\nNativeConnection.prototype.listDatabases = async function listDatabases() {\n  await this._waitForConnect();\n\n  return await this.db.admin().listDatabases();\n};\n\n/*!\n * ignore\n */\n\nNativeConnection.prototype.createClient = async function createClient(uri, options) {\n  if (typeof uri !== 'string') {\n    throw new MongooseError('The `uri` parameter to `openUri()` must be a ' +\n      `string, got \"${typeof uri}\". Make sure the first parameter to ` +\n      '`mongoose.connect()` or `mongoose.createConnection()` is a string.');\n  }\n\n  if (this._destroyCalled) {\n    throw new MongooseError(\n      'Connection has been closed and destroyed, and cannot be used for re-opening the connection. ' +\n      'Please create a new connection with `mongoose.createConnection()` or `mongoose.connect()`.'\n    );\n  }\n\n  if (this.readyState === STATES.connecting || this.readyState === STATES.connected) {\n    if (this._connectionString !== uri) {\n      throw new MongooseError('Can\\'t call `openUri()` on an active connection with ' +\n        'different connection strings. Make sure you aren\\'t calling `mongoose.connect()` ' +\n        'multiple times. See: https://mongoosejs.com/docs/connections.html#multiple_connections');\n    }\n  }","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/drivers/node-mongodb-native/connection.js#L216-L252","documentation":"NativeConnection.createClient() - the engine behind mongoose.connect() and mongoose.createConnection() - validates that the first parameter is a string URI before doing anything else. Passing undefined, an object, a MongoClient, or any other non-string throws this MongooseError reporting the actual typeof, because the connection string is the one required input for opening a connection.","triggerScenarios":"mongoose.connect(process.env.MONGO_URI) when MONGO_URI is unset; passing an options object or a MongoClient as the first argument; mongoose.createConnection(dbConfigObject) instead of a URI string.","commonSituations":"Missing .env file or dotenv imported after the connect call; env var name typo (MONGO_URL vs MONGO_URI); code written for a client-first API (should use conn.setClient()); CI without configured secrets.","solutions":["Load environment config first (import 'dotenv/config' at the top) and fail fast if the URI is missing.","Pass the string URI as the first argument: await mongoose.connect('mongodb://localhost:27017/test', options).","If you already have a connected MongoClient, use conn.setClient(client) instead of passing the client to connect().","Check for typos in the variable holding the URI."],"exampleFix":"// before\nimport mongoose from 'mongoose';\nawait mongoose.connect(process.env.MONGO_URI); // undefined if .env not loaded\n\n// after\nimport 'dotenv/config';\nconst uri = process.env.MONGO_URI;\nif (typeof uri !== 'string' || uri.length === 0) {\n  throw new Error('MONGO_URI is not set');\n}\nawait mongoose.connect(uri);","handlingStrategy":"validation","validationCode":"function assertMongoUri(uri) {\n  if (typeof uri !== 'string' || uri.length === 0) {\n    throw new Error(`Connection URI must be a non-empty string, got ${typeof uri}`);\n  }\n  return uri;\n}\nawait mongoose.connect(assertMongoUri(process.env.MONGO_URI));","typeGuard":"function isMongoUri(v) {\n  return typeof v === 'string' && v.startsWith('mongodb');\n}","tryCatchPattern":null,"preventionTips":["Load dotenv (or the platform secret manager) at the very top of the entrypoint, before any connect call.","Fail fast with a clear message when required env vars are missing instead of passing undefined downstream.","Add a CI startup smoke test that runs connect against a throwaway database to catch config drift."],"tags":["mongoose","connection-string","env-var","configuration","startup"],"backgroundTag":"missing-connection-string","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}