mongodb/node-mongodb-native · error · MongoParseError

Option 'family' must be 4 or 6 got

Error message

Option 'family' must be 4 or 6 got ${transformValue}.

What it means

The `family` option forces IPv4 or IPv6 for DNS resolution. The transform at src/connection_string.ts:821 parses the value to an integer via getIntFromOptions and only accepts 4 or 6; anything else throws MongoParseError at src/connection_string.ts:826. Note getIntFromOptions itself first throws if the value is not a parseable integer.

Solutions

1. Pass `4` for IPv4-only or `6` for IPv6-only.
2. Omit the option entirely to let the OS/server pick the family.
3. If the value comes from config as a string, parse and validate it equals 4 or 6 before constructing the client.

Example fix

// before
new MongoClient(uri, { family: 'ipv4' });

// after
new MongoClient(uri, { family: 4 });

if (opts.family != null && opts.family !== 4 && opts.family !== 6) {
  throw new Error(`family must be 4 or 6, got ${opts.family}`);
}

function isFamily(v: unknown): v is 4 | 6 { return v === 4 || v === 6; }

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

When it happens

Trigger: Passing `family: 5`, `family: 0`, `family: 'ipv4'`, `family: 'AF_INET'`, or `?family=10`. The error message echoes the parsed integer that failed the 4-or-6 check.

Common situations: Confusing with POSIX socket family constants or with other libraries that accept 'ipv4'/'ipv6' strings; copy-pasting a `family` value from a Node `net.connect` config; treating 0 as 'unspecified'.

Related errors

• is not a valid compression mechanism. Must be one of: .
• compressors must be an array or a comma-delimited list of…
• Auth mechanism property ALLOWED_HOSTS must be an array of…
• AuthContext must provide credentials.
• AuthContext must provide credentials.

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

Appendix: source

Thrown at src/connection_string.ts:826

  dbName: {
    type: 'string'
  },
  directConnection: {
    default: false,
    type: 'boolean'
  },
  driverInfo: {
    default: {},
    type: 'record'
  },
  enableUtf8Validation: { type: 'boolean', default: true },
  family: {
    transform({ name, values: [value] }): 4 | 6 {
      const transformValue = getIntFromOptions(name, value);
      if (transformValue === 4 || transformValue === 6) {
        return transformValue;
      }
      throw new MongoParseError(`Option 'family' must be 4 or 6 got ${transformValue}.`);
    }
  },
  fieldsAsRaw: {
    type: 'record'
  },
  forceServerObjectId: {
    default: false,
    type: 'boolean'
  },
  fsync: {
    deprecated: 'Please use journal instead',
    target: 'writeConcern',
    transform({ name, options, values: [value] }): WriteConcern {
      const wc = WriteConcern.fromOptions({
        writeConcern: {
          ...options.writeConcern,
          fsync: getBoolean(name, value)
        }

View on GitHub (pinned to dce7939f86)