{"record":{"id":"d3ac4c0151e061ee","repo":"mongodb/node-mongodb-native","slug":"readpreference-tags-must-be-an-array","errorCode":null,"errorMessage":"ReadPreference tags must be an array","messagePattern":"ReadPreference tags must be an array","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/read_preference.ts","lineNumber":92,"sourceCode":"  public static primaryPreferred = new ReadPreference(ReadPreferenceMode.primaryPreferred);\n  public static secondary = new ReadPreference(ReadPreferenceMode.secondary);\n  public static secondaryPreferred = new ReadPreference(ReadPreferenceMode.secondaryPreferred);\n  public static nearest = new ReadPreference(ReadPreferenceMode.nearest);\n\n  /**\n   * @param mode - A string describing the read preference mode (primary|primaryPreferred|secondary|secondaryPreferred|nearest)\n   * @param tags - A tag set used to target reads to members with the specified tag(s). tagSet is not available if using read preference mode primary.\n   * @param options - Additional read preference options\n   */\n  constructor(mode: ReadPreferenceMode, tags?: TagSet[], options?: ReadPreferenceOptions) {\n    if (!ReadPreference.isValid(mode)) {\n      throw new MongoInvalidArgumentError(`Invalid read preference mode ${JSON.stringify(mode)}`);\n    }\n    if (options == null && typeof tags === 'object' && !Array.isArray(tags)) {\n      options = tags;\n      tags = undefined;\n    } else if (tags && !Array.isArray(tags)) {\n      throw new MongoInvalidArgumentError('ReadPreference tags must be an array');\n    }\n\n    this.mode = mode;\n    this.tags = tags;\n    this.hedge = options?.hedge;\n    this.maxStalenessSeconds = undefined;\n\n    options = options ?? {};\n    if (options.maxStalenessSeconds != null) {\n      if (options.maxStalenessSeconds <= 0) {\n        throw new MongoInvalidArgumentError('maxStalenessSeconds must be a positive integer');\n      }\n\n      this.maxStalenessSeconds = options.maxStalenessSeconds;\n    }\n\n    if (this.mode === ReadPreference.PRIMARY) {\n      if (this.tags && Array.isArray(this.tags) && this.tags.length > 0) {","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/read_preference.ts#L74-L110","documentation":"Thrown by the ReadPreference constructor (src/read_preference.ts:92) when the second argument is a non-array, non-object-or-an-object-that-should-be-options. If the constructor sees a truthy tags argument that is not an array (and not a plain object interpreted as options), it raises MongoInvalidArgumentError. Tags must be a TagSet[] (array of objects).","triggerScenarios":"Calling new ReadPreference('secondary', { region: 'us' }) intending a single tag set — the driver expects an array of tag-set objects. Also new ReadPreference('secondary', 'us') or new ReadPreference('secondary', 5).","commonSituations":"Confusing the tags argument (array of tag sets) with a single tag-set object or with the options object.","solutions":["Pass tags as an array: new ReadPreference('secondary', [{ region: 'us' }]).","If you meant to pass options, omit tags or pass undefined as the second argument."],"exampleFix":"// before\nconst rp = new ReadPreference('secondary', { region: 'us' });\n// after\nconst rp = new ReadPreference('secondary', [{ region: 'us' }]);","handlingStrategy":"validation","validationCode":"function buildRP(mode, tags) {\n  const tagArr = tags == null ? undefined : Array.isArray(tags) ? tags : [tags];\n  return new ReadPreference(mode, tagArr);\n}","typeGuard":"function isTagSetArray(v): v is Array<Record<string,string>> {\n  return Array.isArray(v) && v.every(t => t != null && typeof t === 'object');\n}","tryCatchPattern":"try {\n  new ReadPreference('secondary', tags);\n} catch (e) {\n  if (e instanceof MongoInvalidArgumentError && /tags must be an array/.test(e.message)) {\n    // coerce to array and retry\n  }\n  throw e;\n}","preventionTips":["Always pass tags as [{ key: 'value' }] (an array of tag-set objects).","Distinguish the tags argument from the options argument in the constructor signature.","Document your tag-set convention in shared config helpers."],"tags":["read-preference","validation","invalid-argument","tags"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}