mongodb/node-mongodb-native · error · MongoParseError

Invalid port (zero) with hostname

Error message

Invalid port (zero) with hostname

What it means

Thrown by the HostAddress constructor when a connection-string host has a port that resolves to 0. Port 0 is invalid for a hostname-based address (it means 'OS-assigned' in sockets and is never correct for a MongoDB endpoint). Raised as MongoParseError during connection-string host parsing.

Solutions

1. Set a valid port (default MongoDB port is 27017) or omit the port to use the default.
2. If building connection strings dynamically, default unset ports to 27017 rather than 0.
3. For Unix domain sockets use the socketPath form instead of a host:port pair.

Example fix

// before
const uri = 'mongodb://localhost:0';

// after
const uri = 'mongodb://localhost:27017';

function buildUri(host: string, port?: number): string {
  const p = port && port > 0 ? port : 27017;
  return `mongodb://${host}:${p}`;
}

function isValidPort(p: unknown): p is number {
  return typeof p === 'number' && Number.isInteger(p) && p > 0 && p <= 65535;
}

try {
  const client = new MongoClient(uri);
  await client.connect();
} catch (e) {
  if (e instanceof MongoParseError && /Invalid port/.test(e.message)) {
    // fix the connection string port and retry
  } else throw e;
}

When it happens

Trigger: Using a connection string like mongodb://host:0 or mongodb://host:0/db where the explicit port is 0. Also if a programmatic HostAddress is constructed with port 0 alongside a hostname.

Common situations: Typo or misconfiguration in the connection string, or code that builds host:port pairs and defaults to 0 when the port variable is unset. Using a placeholder of 0 in config templates that is not replaced before runtime.

Related errors

• authMechanism one of
• Can only specify both of proxy username/password or neither
• Cannot have undefined values in key value pairs
• Expected to be stringified int value, got
• Invalid server API version=

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

Appendix: source

Thrown at src/utils.ts:920

    let normalized = decodeURIComponent(hostname).toLowerCase();
    if (normalized.startsWith('[') && normalized.endsWith(']')) {
      this.isIPv6 = true;
      normalized = normalized.substring(1, hostname.length - 1);
    }

    this.host = normalized.toLowerCase();

    if (typeof port === 'number') {
      this.port = port;
    } else if (typeof port === 'string' && port !== '') {
      this.port = Number.parseInt(port, 10);
    } else {
      this.port = 27017;
    }

    if (this.port === 0) {
      throw new MongoParseError('Invalid port (zero) with hostname');
    }
    Object.freeze(this);
  }

  [Symbol.for('nodejs.util.inspect.custom')](): string {
    return this.inspect();
  }

  inspect(): string {
    return `new HostAddress('${this.toString()}')`;
  }

  toString(): string {
    if (typeof this.host === 'string') {
      if (this.isIPv6) {
        return `[${this.host}]:${this.port}`;
      }
      return `${this.host}:${this.port}`;

View on GitHub (pinned to dce7939f86)