mongodb/node-mongodb-native · error · MongoParseError

URI cannot contain `serverApi`, it can only be passed to the

Error message

URI cannot contain `serverApi`, it can only be passed to the client

What it means

Thrown by parseOptions when the connection URI's query string contains a `serverApi` parameter (e.g. `?serverApi=1`). The driver expects serverApi to be supplied only via the MongoClient options object because it requires a structured {version, strict, deprecationErrors} value, not a single URI scalar. Including it in the URI is always a configuration mistake.

Source

Thrown at src/connection_string.ts:313

    }

    if (!isReadPreferenceTags && values.includes('')) {
      throw new MongoAPIError(`URI option "${key}" cannot be specified with no value`);
    }

    if (!urlOptions.has(key)) {
      urlOptions.set(key, values);
    }
  }

  const objectOptions = new CaseInsensitiveMap<unknown>(
    Object.entries(options).filter(([, v]) => v != null)
  );

  // Validate options that can only be provided by one of uri or object

  if (urlOptions.has('serverApi')) {
    throw new MongoParseError(
      'URI cannot contain `serverApi`, it can only be passed to the client'
    );
  }

  const uriMechanismProperties = urlOptions.get('authMechanismProperties');
  if (uriMechanismProperties) {
    for (const property of uriMechanismProperties) {
      if (/(^|,)ALLOWED_HOSTS:/.test(property as string)) {
        throw new MongoParseError(
          'Auth mechanism property ALLOWED_HOSTS is not allowed in the connection string.'
        );
      }
    }
  }

  if (objectOptions.has('loadBalanced')) {
    throw new MongoParseError('loadBalanced is only a valid option in the URI');
  }

View on GitHub (pinned to 3366c21a63)

Solutions

1. Remove `serverApi=...` from the URI query string.
2. Pass serverApi through the options object: new MongoClient(uri, { serverApi: { version: ServerApiVersion.v1, strict: true, deprecationErrors: true } }).
3. If you generated the URI from a config helper, fix the helper so serverApi is excluded from query params.

Example fix

// before
const c = new MongoClient('mongodb://host:27017/?serverApi=v1');
// after
import { ServerApiVersion } from 'mongodb';
const c = new MongoClient('mongodb://host:27017/', {
  serverApi: { version: ServerApiVersion.v1, strict: true, deprecationErrors: true }
});

const u = new URL(uri);
if (u.searchParams.has('serverApi')) {
  throw new Error('serverApi must be passed via MongoClient options, not the URI');
}

try {
  client = new MongoClient(uri, opts);
} catch (e) {
  if (e instanceof MongoParseError && /serverApi/.test(e.message)) { /* strip serverApi from URI and retry */ }
  else throw e;
}

When it happens

Trigger: Constructing MongoClient with a URI like 'mongodb://host:27017/?serverApi=1' or 'mongodb+srv://cluster.example/?serverApi=v1'. The check at connection_string.ts:312 fires as soon as CaseInsensitiveMap urlOptions reports the key 'serverApi'.

Common situations: Copy-pasting an option list into a URI builder; migrating from a tutorial that mixed URI and object options; trying to enable stable API by appending query params instead of using the options argument.

Related errors

• loadBalanced is only a valid option in the URI
• All values of tls/ssl must be the same.
• ${optionWord} ${Array.from(unsupportedOptions).join(', ')} $
• SRV URI does not support directConnection
• Cannot use srvMaxHosts or srvServiceName with a non-srv conn

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/108e2030d8d480a0.json. Report an issue: GitHub.