mongodb/node-mongodb-native · error · MongoParseError

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

Error message

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

What it means

serverApi is intentionally not a URI option. It must be passed as a client option (e.g. { serverApi: ServerApiVersion.v1 }) because it controls wire protocol behavior that the driver must negotiate during connection setup, before option merging. If it appears in the URI query string, the driver throws.

Solutions

1. Remove serverApi from the URI.
2. Pass it via the options object: new MongoClient(uri, { serverApi: ServerApiVersion.v1 }).

Example fix

// before
new MongoClient('mongodb://h/db?serverApi=1');
// after
new MongoClient('mongodb://h/db', { serverApi: ServerApiVersion.v1 });

function assertServerApiNotInUri(uri: string) {
  if (/\bserverApi=/i.test(uri.split('?')[1] ?? '')) {
    throw new Error('serverApi must be passed via the options object, not the URI');
  }
}

When it happens

Trigger: A URI like 'mongodb://h/db?serverApi=1'. Detected after URL/option collection by checking urlOptions.has('serverApi').

Common situations: Trying to pin API version via the connection string, or migrating a URI from another driver that allows it.

Related errors

• All values of tls/ssl must be the same.
• Auth mechanism property ALLOWED_HOSTS is not allowed in the…
• authMechanism requires an authSource of '$external
• Cannot combine replicaSet option with srvMaxHosts
• Cannot have empty URI params in DNS TXT Record

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/108e2030d8d480a0. Report an issue: GitHub.

Appendix: 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 dce7939f86)