{"record":{"id":"8f78989e5bff97a9","repo":"payloadcms/payload","slug":"error-missing-mongodb-connection-url","errorCode":null,"errorMessage":"Error: missing MongoDB connection URL.","messagePattern":"Error: missing MongoDB connection URL\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/db-mongodb/src/connect.ts","lineNumber":22,"sourceCode":"import mongoose from 'mongoose'\nimport { defaultBeginTransaction } from 'payload'\n\nimport type { MongooseAdapter } from './index.js'\n\nexport const connect: Connect = async function connect(\n  this: MongooseAdapter,\n  options = {\n    hotReload: false,\n  },\n) {\n  const { hotReload } = options\n\n  if (this.url === false) {\n    return\n  }\n\n  if (typeof this.url !== 'string') {\n    throw new Error('Error: missing MongoDB connection URL.')\n  }\n\n  const urlToConnect = this.url\n\n  const connectionOptions: ConnectOptions = {\n    autoIndex: true,\n    ...this.connectOptions,\n  }\n\n  if (hotReload) {\n    connectionOptions.autoIndex = false\n  }\n\n  try {\n    if (!this.connection) {\n      this.connection = await mongoose.createConnection(urlToConnect, connectionOptions).asPromise()\n      if (this.afterCreateConnection) {\n        await this.afterCreateConnection(this)","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/db-mongodb/src/connect.ts#L4-L40","documentation":"The MongoDB adapter connect() returns early if this.url === false (explicit opt-out), but throws when this.url is any non-string value (undefined, null, number). The adapter requires either a string URL or the literal false sentinel.","triggerScenarios":"Configuring mongooseAdapter without a url, or with url set to undefined/null because the env var (e.g. DATABASE_URI) was not loaded; passing a non-string by mistake; misconfigured adapter options object.","commonSituations":"Missing or misnamed MONGODB_URI/DATABASE_URI env var; .env not loaded in the current process; adapter built from a config where url is conditionally undefined.","solutions":["Set the adapter url to a valid mongodb:// (or mongodb+srv://) connection string.","If you intentionally have no DB (e.g. build/compile step), pass url: false explicitly to skip connect.","Ensure the env var is loaded before building the adapter (load .env, check process.env spelling).","Log typeof adapter.url before connect to confirm it is a string."],"exampleFix":"// before\nnew MongooseAdapter({ payload, url: process.env.DATABASE_URI }) // DATABASE_URI unset -> undefined\n\n// after\nnew MongooseAdapter({\n  payload,\n  url: process.env.DATABASE_URI ?? 'mongodb://127.0.0.1:27017/payload',\n})\n// or, to skip connection entirely:\nnew MongooseAdapter({ payload, url: false })","handlingStrategy":"type-guard","validationCode":"function resolveMongoUrl(): string | false {\n  const url = process.env.DATABASE_URI\n  if (url === undefined || url === null || url === '') {\n    throw new Error('DATABASE_URI env var is not set')\n  }\n  return url\n}\nnew MongooseAdapter({ payload, url: resolveMongoUrl() })","typeGuard":"function isMongoUrlOrFalse(x: unknown): x is string | false {\n  return x === false || typeof x === 'string'\n}\n// usage\nif (!isMongoUrlOrFalse(config.url)) {\n  throw new Error('MongooseAdapter.url must be a connection string or false')\n}","tryCatchPattern":null,"preventionTips":["Always pass a string URL or the literal false to the adapter.","Load .env before constructing the adapter; check env var names.","Default url: false in build steps that do not need a DB."],"tags":["db-mongodb","database","connection","config","adapter"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}