mongodb/node-mongodb-native · error · MongoParseError

directConnection option requires exactly one host

Error message

directConnection option requires exactly one host

What it means

Thrown when directConnection is enabled but the URI's host list does not contain exactly one host (connection_string.ts:500-502). directConnection tells the driver to talk to one specific server without SDAM discovery, so multiple hosts are meaningless and zero hosts are impossible by construction.

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 3366c21a63)

Solutions

1. Reduce the URI to exactly one host when using directConnection.
2. Or remove directConnection to let the driver discover the rest of the topology.
3. For standalone servers, use 'mongodb://onehost:27017/?directConnection=true'.

Example fix

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

const hostPart = uri.split('://')[1]?.split('/')[0]?.split('?')[0] ?? '';
const hostCount = hostPart.split(',').filter(Boolean).length;
if ((opts.directConnection || new URL(uri).searchParams.get('directConnection') === 'true') && hostCount !== 1) {
  throw new Error(`directConnection requires exactly one host (got ${hostCount})`);
}

When it happens

Trigger: URI like 'mongodb://h1:27017,h2:27017/?directConnection=true' or a replica-set style URI with multiple hosts plus the directConnection flag.

Common situations: Enabling directConnection on a borrowed multi-host URI; building a URI from a host array while always setting directConnection=true.

Related errors

• SRV URI does not support directConnection
• Driver attempted to initialize in load balancing mode, but t
• URI cannot contain `serverApi`, it can only be passed to the
• loadBalanced is only a valid option in the URI
• All values of tls/ssl must be the same.

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