{"record":{"id":"f4ef794564d9f800","repo":"mongodb/node-mongodb-native","slug":"option-family-must-be-4-or-6-got-transformvalu","errorCode":null,"errorMessage":"Option 'family' must be 4 or 6 got ${transformValue}.","messagePattern":"Option 'family' must be 4 or 6 got (.+?)\\.","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":826,"sourceCode":"  dbName: {\n    type: 'string'\n  },\n  directConnection: {\n    default: false,\n    type: 'boolean'\n  },\n  driverInfo: {\n    default: {},\n    type: 'record'\n  },\n  enableUtf8Validation: { type: 'boolean', default: true },\n  family: {\n    transform({ name, values: [value] }): 4 | 6 {\n      const transformValue = getIntFromOptions(name, value);\n      if (transformValue === 4 || transformValue === 6) {\n        return transformValue;\n      }\n      throw new MongoParseError(`Option 'family' must be 4 or 6 got ${transformValue}.`);\n    }\n  },\n  fieldsAsRaw: {\n    type: 'record'\n  },\n  forceServerObjectId: {\n    default: false,\n    type: 'boolean'\n  },\n  fsync: {\n    deprecated: 'Please use journal instead',\n    target: 'writeConcern',\n    transform({ name, options, values: [value] }): WriteConcern {\n      const wc = WriteConcern.fromOptions({\n        writeConcern: {\n          ...options.writeConcern,\n          fsync: getBoolean(name, value)\n        }","sourceCodeStart":808,"sourceCodeEnd":844,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/connection_string.ts#L808-L844","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Pass `4` for IPv4-only or `6` for IPv6-only.","Omit the option entirely to let the OS/server pick the family.","If the value comes from config as a string, parse and validate it equals 4 or 6 before constructing the client."],"exampleFix":"// before\nnew MongoClient(uri, { family: 'ipv4' });\n\n// after\nnew MongoClient(uri, { family: 4 });","handlingStrategy":"validation","validationCode":"if (opts.family != null && opts.family !== 4 && opts.family !== 6) {\n  throw new Error(`family must be 4 or 6, got ${opts.family}`);\n}","typeGuard":"function isFamily(v: unknown): v is 4 | 6 { return v === 4 || v === 6; }","tryCatchPattern":"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; }","preventionTips":["Type the field as `family?: 4 | 6` in your own config schema.","Reject strings like 'ipv4' at the config boundary.","Omit the option when you do not need to force a family."],"tags":["connection-options","networking","configuration"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}