payloadcms/payload · critical · Error

Error: missing MongoDB connection URL.

Error message

Error: missing MongoDB connection URL.

What it means

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.

Source

Thrown at packages/db-mongodb/src/connect.ts:22

import mongoose from 'mongoose'
import { defaultBeginTransaction } from 'payload'

import type { MongooseAdapter } from './index.js'

export const connect: Connect = async function connect(
  this: MongooseAdapter,
  options = {
    hotReload: false,
  },
) {
  const { hotReload } = options

  if (this.url === false) {
    return
  }

  if (typeof this.url !== 'string') {
    throw new Error('Error: missing MongoDB connection URL.')
  }

  const urlToConnect = this.url

  const connectionOptions: ConnectOptions = {
    autoIndex: true,
    ...this.connectOptions,
  }

  if (hotReload) {
    connectionOptions.autoIndex = false
  }

  try {
    if (!this.connection) {
      this.connection = await mongoose.createConnection(urlToConnect, connectionOptions).asPromise()
      if (this.afterCreateConnection) {
        await this.afterCreateConnection(this)

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Set the adapter url to a valid mongodb:// (or mongodb+srv://) connection string.
2. If you intentionally have no DB (e.g. build/compile step), pass url: false explicitly to skip connect.
3. Ensure the env var is loaded before building the adapter (load .env, check process.env spelling).
4. Log typeof adapter.url before connect to confirm it is a string.

Example fix

// before
new MongooseAdapter({ payload, url: process.env.DATABASE_URI }) // DATABASE_URI unset -> undefined

// after
new MongooseAdapter({
  payload,
  url: process.env.DATABASE_URI ?? 'mongodb://127.0.0.1:27017/payload',
})
// or, to skip connection entirely:
new MongooseAdapter({ payload, url: false })

function resolveMongoUrl(): string | false {
  const url = process.env.DATABASE_URI
  if (url === undefined || url === null || url === '') {
    throw new Error('DATABASE_URI env var is not set')
  }
  return url
}
new MongooseAdapter({ payload, url: resolveMongoUrl() })

function isMongoUrlOrFalse(x: unknown): x is string | false {
  return x === false || typeof x === 'string'
}
// usage
if (!isMongoUrlOrFalse(config.url)) {
  throw new Error('MongooseAdapter.url must be a connection string or false')
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Error: cannot connect to MongoDB: ${msg}
• Error: cannot connect to SQLite: ${message}
• Invalid database type given. Valid types are: ${Object.value
• Localization is not enabled in payload config
• ${collectionSlug ? 'Collection' : 'Global'} not found: ${col

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/8f78989e5bff97a9. Report an issue: GitHub.