mongodb/node-mongodb-native · error · MongoParseError

Invalid server API version=

Error message

Invalid server API version=${versionToValidate}; must be in the following enum: ["${Object.values(ServerApiVersion).join('", "')}"]

What it means

Thrown by MongoParseError at src/connection_string.ts:765 in the `serverApi` transform when `version` is present but is not one of the `ServerApiVersion` enum values (currently only `'1'`). Distinct from error 198 which fires when version is missing entirely; this one fires when version is the wrong value. The message echoes the bad version and lists valid values.

Solutions

Use `version: ServerApiVersion.v1` (i.e. the string '1') — the only currently supported server API version.
Import `ServerApiVersion` from 'mongodb' to avoid hard-coding the wrong literal.
If you need a different API version, check the driver release notes — newer ServerApiVersions are added only when the server ships them.

Example fix

// before
new MongoClient(uri, { serverApi: { version: 'v1' } })

// after
import { ServerApiVersion } from 'mongodb'
new MongoClient(uri, { serverApi: { version: ServerApiVersion.v1 } })

Defensive patterns

Strategy: validation

Validate before calling

import { ServerApiVersion } from 'mongodb';
function assertServerApiVersionValid(serverApi) { const v = typeof serverApi === 'string' ? serverApi : serverApi?.version; if (v != null && !Object.values(ServerApiVersion).includes(v)) throw new Error(`serverApi.version must be one of ${Object.values(ServerApiVersion).join(', ')}`); }

Type guard

import { ServerApiVersion } from 'mongodb';
function isServerApiVersion(v): v is ServerApiVersion { return Object.values(ServerApiVersion).some(valid => valid === v); }

Try / catch

try { new MongoClient(uri, { serverApi }); } catch (e) { if (e instanceof MongoParseError && /Invalid server API version/.test(e.message)) { serverApi = { ...serverApi, version: ServerApiVersion.v1 }; } else throw e; }

Prevention

Import `ServerApiVersion` from 'mongodb' and reference `ServerApiVersion.v1` instead of typing the literal.
Treat the value as an enum, not a free-form version string.

When it happens

Trigger: `{ serverApi: { version: '2' } }`, `{ serverApi: { version: 1 } }` (number not string '1'), `{ serverApi: { version: 'v1' } }`, or `{ serverApi: { version: 'stable' } }`.

Common situations: Assuming a numeric `1` works (must be the string `'1'`); using `'v1'` because of the enum key name; guessing `'stable'` because of Atlas API terminology.

Related errors

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

Appendix: source

Thrown at src/connection_string.ts:765

  },
  bsonRegExp: {
    type: 'boolean'
  },
  serverApi: {
    target: 'serverApi',
    transform({ values: [version] }): ServerApi {
      const serverApiToValidate =
        typeof version === 'string' ? ({ version } as ServerApi) : (version as ServerApi);
      const versionToValidate = serverApiToValidate && serverApiToValidate.version;
      if (!versionToValidate) {
        throw new MongoParseError(
          `Invalid \`serverApi\` property; must specify a version from the following enum: ["${Object.values(
            ServerApiVersion
          ).join('", "')}"]`
        );
      }
      if (!Object.values(ServerApiVersion).some(v => v === versionToValidate)) {
        throw new MongoParseError(
          `Invalid server API version=${versionToValidate}; must be in the following enum: ["${Object.values(
            ServerApiVersion
          ).join('", "')}"]`
        );
      }
      return serverApiToValidate;
    }
  },
  checkKeys: {
    type: 'boolean'
  },
  compressors: {
    default: 'none',
    target: 'compressors',
    transform({ values }) {
      const compressionList = new Set();
      for (const compVal of values as (CompressorName[] | string)[]) {
        const compValArray = typeof compVal === 'string' ? compVal.split(',') : compVal;

View on GitHub (pinned to dce7939f86)