mongodb/node-mongodb-native · error · MongoParseError

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

Error message

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

What it means

The `family` option restricts the IP stack to IPv4 or IPv6 and must be exactly `4` or `6`. The transform (src/connection_string.ts:820-827) parses the value to an integer and rejects anything other than 4 or 6.

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

Solutions

1. Set `family: 4` for IPv4-only or `family: 6` for IPv6-only
2. Omit the option to allow both stacks (autoSelectFamily handles dual-stack selection)

Example fix

// before
new MongoClient(uri, { family: 0 });
// after
new MongoClient(uri, { family: 6 }); // IPv6 only

function isValidFamily(v) {
  const n = Number(v);
  return n === 4 || n === 6;
}
if (options.family != null && !isValidFamily(options.family)) {
  throw new TypeError('family must be 4 or 6');
}

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

When it happens

Trigger: `{ family: 5 }`; `{ family: 0 }`; `{ family: '4.5' }` (parses to 4 only if parseInt, but a non-integer string may fail earlier in getIntFromOptions); `{ family: 10 }`.

Common situations: Misunderstanding family as a count or boolean; assuming 0 means 'both'; porting Node `net` family semantics with a wrong value.

Related errors

• Descriptors missing a type must define a transform
• ${name} must be an object with 'username' and 'password' pro
• authMechanism one of ${mechanisms}, got ${value}
• Invalid `serverApi` property; must specify a version from th
• Invalid server API version=${versionToValidate}; must be in

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