{"record":{"id":"108e2030d8d480a0","repo":"mongodb/node-mongodb-native","slug":"uri-cannot-contain-serverapi-it-can-only-be-pas","errorCode":null,"errorMessage":"URI cannot contain `serverApi`, it can only be passed to the client","messagePattern":"URI cannot contain `serverApi`, it can only be passed to the client","errorType":"exception","errorClass":"MongoParseError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":313,"sourceCode":"    }\n\n    if (!isReadPreferenceTags && values.includes('')) {\n      throw new MongoAPIError(`URI option \"${key}\" cannot be specified with no value`);\n    }\n\n    if (!urlOptions.has(key)) {\n      urlOptions.set(key, values);\n    }\n  }\n\n  const objectOptions = new CaseInsensitiveMap<unknown>(\n    Object.entries(options).filter(([, v]) => v != null)\n  );\n\n  // Validate options that can only be provided by one of uri or object\n\n  if (urlOptions.has('serverApi')) {\n    throw new MongoParseError(\n      'URI cannot contain `serverApi`, it can only be passed to the client'\n    );\n  }\n\n  const uriMechanismProperties = urlOptions.get('authMechanismProperties');\n  if (uriMechanismProperties) {\n    for (const property of uriMechanismProperties) {\n      if (/(^|,)ALLOWED_HOSTS:/.test(property as string)) {\n        throw new MongoParseError(\n          'Auth mechanism property ALLOWED_HOSTS is not allowed in the connection string.'\n        );\n      }\n    }\n  }\n\n  if (objectOptions.has('loadBalanced')) {\n    throw new MongoParseError('loadBalanced is only a valid option in the URI');\n  }","sourceCodeStart":295,"sourceCodeEnd":331,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/connection_string.ts#L295-L331","documentation":"serverApi is intentionally not a URI option. It must be passed as a client option (e.g. { serverApi: ServerApiVersion.v1 }) because it controls wire protocol behavior that the driver must negotiate during connection setup, before option merging. If it appears in the URI query string, the driver throws.","triggerScenarios":"A URI like 'mongodb://h/db?serverApi=1'. Detected after URL/option collection by checking urlOptions.has('serverApi').","commonSituations":"Trying to pin API version via the connection string, or migrating a URI from another driver that allows it.","solutions":["Remove serverApi from the URI.","Pass it via the options object: new MongoClient(uri, { serverApi: ServerApiVersion.v1 })."],"exampleFix":"// before\nnew MongoClient('mongodb://h/db?serverApi=1');\n// after\nnew MongoClient('mongodb://h/db', { serverApi: ServerApiVersion.v1 });","handlingStrategy":"validation","validationCode":"function assertServerApiNotInUri(uri: string) {\n  if (/\\bserverApi=/i.test(uri.split('?')[1] ?? '')) {\n    throw new Error('serverApi must be passed via the options object, not the URI');\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass serverApi only via { serverApi: ServerApiVersion.v1 }.","Keep URI and options concerns separated in your config layer."],"tags":["connection-string","server-api","validation"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}