{"record":{"id":"133a97a2b0f89501","repo":"mongodb/node-mongodb-native","slug":"invalid-port-zero-with-hostname","errorCode":null,"errorMessage":"Invalid port (zero) with hostname","messagePattern":"Invalid port \\(zero\\) with hostname","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/utils.ts","lineNumber":920,"sourceCode":"\n    let normalized = decodeURIComponent(hostname).toLowerCase();\n    if (normalized.startsWith('[') && normalized.endsWith(']')) {\n      this.isIPv6 = true;\n      normalized = normalized.substring(1, hostname.length - 1);\n    }\n\n    this.host = normalized.toLowerCase();\n\n    if (typeof port === 'number') {\n      this.port = port;\n    } else if (typeof port === 'string' && port !== '') {\n      this.port = Number.parseInt(port, 10);\n    } else {\n      this.port = 27017;\n    }\n\n    if (this.port === 0) {\n      throw new MongoParseError('Invalid port (zero) with hostname');\n    }\n    Object.freeze(this);\n  }\n\n  [Symbol.for('nodejs.util.inspect.custom')](): string {\n    return this.inspect();\n  }\n\n  inspect(): string {\n    return `new HostAddress('${this.toString()}')`;\n  }\n\n  toString(): string {\n    if (typeof this.host === 'string') {\n      if (this.isIPv6) {\n        return `[${this.host}]:${this.port}`;\n      }\n      return `${this.host}:${this.port}`;","sourceCodeStart":902,"sourceCodeEnd":938,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/utils.ts#L902-L938","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set a valid port (default MongoDB port is 27017) or omit the port to use the default.","If building connection strings dynamically, default unset ports to 27017 rather than 0.","For Unix domain sockets use the socketPath form instead of a host:port pair."],"exampleFix":"// before\nconst uri = 'mongodb://localhost:0';\n\n// after\nconst uri = 'mongodb://localhost:27017';","handlingStrategy":"validation","validationCode":"function buildUri(host: string, port?: number): string {\n  const p = port && port > 0 ? port : 27017;\n  return `mongodb://${host}:${p}`;\n}","typeGuard":"function isValidPort(p: unknown): p is number {\n  return typeof p === 'number' && Number.isInteger(p) && p > 0 && p <= 65535;\n}","tryCatchPattern":"try {\n  const client = new MongoClient(uri);\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoParseError && /Invalid port/.test(e.message)) {\n    // fix the connection string port and retry\n  } else throw e;\n}","preventionTips":["Validate ports are positive integers (1-65535) before building connection strings.","Default unset ports to 27017 instead of 0 in config templates.","Centralize connection-string construction in a single validated helper."],"tags":["connection-string","configuration","parsing"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}