mongodb/node-mongodb-native · error · MongoParseError

serverMonitoringMode must be one of `auto`, `poll`, or…

Error message

serverMonitoringMode must be one of `auto`, `poll`, or `stream`

What it means

`serverMonitoringMode` selects how the driver monitors servers (heartbeat streaming vs polling vs automatic). The transform at src/connection_string.ts:1091 checks `Object.values(ServerMonitoringMode).includes(value)`. The frozen object at src/sdam/monitor.ts:44 only contains `auto`, `poll`, `stream`; any other value throws MongoParseError at src/connection_string.ts:1093.

Solutions

1. Use exactly `auto`, `poll`, or `stream` (lowercase).
2. Lowercase environment-provided values before passing them in.
3. Omit the option to use the default `auto`.

Example fix

// before
new MongoClient(uri, { serverMonitoringMode: 'automatic' });

// after
new MongoClient(uri, { serverMonitoringMode: 'auto' });

const MODES = ['auto','poll','stream'];
if (opts.serverMonitoringMode != null && !MODES.includes(String(opts.serverMonitoringMode).toLowerCase())) {
  throw new Error(`serverMonitoringMode must be one of ${MODES.join(', ')}`);
}

function isServerMonitoringMode(v: unknown): v is 'auto'|'poll'|'stream' { return typeof v === 'string' && ['auto','poll','stream'].includes(v); }

try { client = new MongoClient(uri, opts); } catch (e) { if (e instanceof MongoParseError && /serverMonitoringMode/.test(e.message)) { opts.serverMonitoringMode = 'auto'; client = new MongoClient(uri, opts); } else throw e; }

When it happens

Trigger: Passing `serverMonitoringMode: 'automatic'`, `'async'`, `'event'`; or setting env `MONGODB_SERVER_MONITORING_MODE=continuous`. Case matters — `'Auto'` or `'STREAM'` will not match.

Common situations: Misremembering the enum name; copy-pasting values from server-side documentation that uses different terminology; case differences from environment variables that aren't lowercased before use.

Related errors

• Options for SrvPoller must exist and include srvHost
• ServerDescription must be provided with a non-empty address
• Topology cannot be constructed from
• Argument "setName" is required if connected to a replica set
• Auth mechanism property ALLOWED_HOSTS must be an array of…

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

Appendix: source

Thrown at src/connection_string.ts:1093

  retryReads: {
    default: true,
    type: 'boolean'
  },
  retryWrites: {
    default: true,
    type: 'boolean'
  },
  runtimeAdapters: {
    type: 'record'
  },
  serializeFunctions: {
    type: 'boolean'
  },
  serverMonitoringMode: {
    default: 'auto',
    transform({ values: [value] }) {
      if (!Object.values(ServerMonitoringMode).includes(value as any)) {
        throw new MongoParseError(
          'serverMonitoringMode must be one of `auto`, `poll`, or `stream`'
        );
      }
      return value;
    }
  },
  serverSelectionTimeoutMS: {
    default: 30000,
    type: 'uint'
  },
  servername: {
    type: 'string'
  },
  socketTimeoutMS: {
    // TODO(NODE-6491): deprecated: 'Please use timeoutMS instead',
    default: 0,
    type: 'uint'
  },

View on GitHub (pinned to dce7939f86)