mongodb/node-mongodb-native · error · MongoParseError

directConnection option requires exactly one host

Error message

directConnection option requires exactly one host

What it means

Thrown by MongoParseError at src/connection_string.ts:501 when `directConnection=true` is set but the URI contains zero or more than one host. Direct connection pins the client to exactly one server, so multiple hosts (or none) contradict the option.

Solutions

1. Keep exactly one host in the URI: `mongodb://oneHost:27017/?directConnection=true`.
2. If you want to connect to multiple hosts, remove `directConnection`.

Example fix

// before
new MongoClient('mongodb://h1:27017,h2:27017/?directConnection=true')

// after (direct to one host)
new MongoClient('mongodb://h1:27017/?directConnection=true')

function assertDirectSingleHost(uri, options = {}) {
  const direct = options.directConnection ?? /directConnection=true/i.test(uri);
  if (!direct) return;
  const hostPart = uri.split('://')[1]?.split('/')[0].split('?')[0];
  const hostCount = hostCount = hostPart.split(',').filter(Boolean).length;
  if (hostCount !== 1) throw new Error('directConnection requires exactly one host.');
}

try { new MongoClient(uri); } catch (e) { if (e instanceof MongoParseError && /directConnection option requires exactly one host/.test(e.message)) { /* pick one host or drop directConnection */ } else throw e; }

When it happens

Trigger: `mongodb://h1:27017,h2:27017/?directConnection=true`, or an empty hosts list with `{ directConnection: true }`, or a trailing comma producing an empty host.

Common situations: Reusing a multi-host replica-set URI and adding `directConnection=true` for debugging; YAML env var templating that injects a host list of varying length.

Related errors

• loadBalanced option not supported when directConnection is…
• SRV URI does not support directConnection
• Cannot limit srv hosts with loadBalanced enabled
• Cannot use srvMaxHosts option with replicaSet
• Cannot use srvMaxHosts or srvServiceName with a non-srv…

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

Appendix: source

Thrown at src/connection_string.ts:501

    if (noUserSpecifiedTLS && noUserSpecifiedSSL) {
      mongoOptions.tls = true;
    }
  } else {
    const userSpecifiedSrvOptions =
      urlOptions.has('srvMaxHosts') ||
      objectOptions.has('srvMaxHosts') ||
      urlOptions.has('srvServiceName') ||
      objectOptions.has('srvServiceName');

    if (userSpecifiedSrvOptions) {
      throw new MongoParseError(
        'Cannot use srvMaxHosts or srvServiceName with a non-srv connection string'
      );
    }
  }

  if (mongoOptions.directConnection && mongoOptions.hosts.length !== 1) {
    throw new MongoParseError('directConnection option requires exactly one host');
  }

  if (
    !mongoOptions.proxyHost &&
    (mongoOptions.proxyPort || mongoOptions.proxyUsername || mongoOptions.proxyPassword)
  ) {
    throw new MongoParseError('Must specify proxyHost if other proxy options are passed');
  }

  if (
    (mongoOptions.proxyUsername && !mongoOptions.proxyPassword) ||
    (!mongoOptions.proxyUsername && mongoOptions.proxyPassword)
  ) {
    throw new MongoParseError('Can only specify both of proxy username/password or neither');
  }

  const proxyOptions = ['proxyHost', 'proxyPort', 'proxyUsername', 'proxyPassword'].map(
    key => urlOptions.get(key) ?? []

View on GitHub (pinned to dce7939f86)