What causes "MONGODB_URL is required" in prisma/prisma?

Set MONGODB_URL in the shell or .env before launching the runtime example.

MONGODB_URL is required

Error message

MONGODB_URL is required

What it means

Thrown by the bundle-size MongoDB example (the runtime variant that calls mongo({ contract }) directly) when MONGODB_URL is unset. Same purpose as the emit variant but on the hand-written runtime path: it needs the URL before db.connect can be invoked. Failing early avoids a misleading lower-level connection error.

Source

Thrown at examples/bundle-size/src/mongo/main.ts:10

import mongo from '@prisma-next/mongo/runtime';
import { contract } from './contract';

const db = mongo({ contract });

async function main(): Promise<void> {
  const url = process.env['MONGODB_URL'];
  const dbName = process.env['MONGODB_DB'] ?? 'bundle_size';
  if (!url) {
    throw new Error('MONGODB_URL is required');
  }
  const runtime = await db.connect({ url, dbName });
  try {
    const plan = db.query.from('notes').limit(10).build();
    const notes = await runtime.execute(plan).toArray();
    console.log(JSON.stringify(notes, null, 2));
  } finally {
    await db.close();
  }
}

await main();

View on GitHub (pinned to 1243cdffbe)

Solutions

Set MONGODB_URL in the shell or .env before launching the runtime example.
Confirm MONGODB_DB (optional, defaults to 'bundle_size') matches your target database.
Ensure the process is launched from the example directory where .env is loaded.
Add the variable to the CI matrix job that runs this example.

Example fix

// before
process.env // { MONGODB_DB: 'bundle_size' }
// after
process.env // { MONGODB_URL: 'mongodb://localhost:27017', MONGODB_DB: 'bundle_size' }

Defensive patterns

Strategy: validation

Validate before calling

const url = process.env['MONGODB_URL'];
const dbName = process.env['MONGODB_DB'] ?? 'bundle_size';
if (typeof url !== 'string' || url.length === 0) {
  console.error('MONGODB_URL is required');
  process.exit(1);
}

Type guard

const isMongodbUrl = (v: unknown): v is string =>
  typeof v === 'string' && /^mongodb(\+srv)?:\/\/.+/.test(v);

Try / catch

try {
  await main();
} catch (error) {
  if (error instanceof Error && error.message === 'MONGODB_URL is required') {
    console.error('Set MONGODB_URL (and optionally MONGODB_DB) before running.');
    process.exit(1);
  }
  throw error;
}

Prevention

Share one connection-config module between main.ts and main-emit.ts so the var is read consistently.
Validate the URL shape (mongodb:// or mongodb+srv://) rather than just truthiness.
Load .env once at the example entry so both generated and hand-written mains see the var.
Document MONGODB_URL / MONGODB_DB in the example README.

When it happens

Trigger: Running the non-emit mongo example (entrypoint importing @prisma-next/mongo/runtime and the local contract) with MONGODB_URL absent from process.env. Happens on direct execution of src/mongo/main.ts.

Common situations: Missing .env in the example workspace, running with a stripped environment in CI, or copying the snippet into another project without porting the env setup.

Related errors

AI-assisted analysis of prisma/prisma@1243cdffbe (2026-08-01). Data as JSON: /data/errors/dfc92e665a9bd3ea.json. Report an issue: GitHub.