{"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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L295-L331","documentation":"Thrown by parseOptions when the connection URI's query string contains a `serverApi` parameter (e.g. `?serverApi=1`). The driver expects serverApi to be supplied only via the MongoClient options object because it requires a structured {version, strict, deprecationErrors} value, not a single URI scalar. Including it in the URI is always a configuration mistake.","triggerScenarios":"Constructing MongoClient with a URI like 'mongodb://host:27017/?serverApi=1' or 'mongodb+srv://cluster.example/?serverApi=v1'. The check at connection_string.ts:312 fires as soon as CaseInsensitiveMap urlOptions reports the key 'serverApi'.","commonSituations":"Copy-pasting an option list into a URI builder; migrating from a tutorial that mixed URI and object options; trying to enable stable API by appending query params instead of using the options argument.","solutions":["Remove `serverApi=...` from the URI query string.","Pass serverApi through the options object: new MongoClient(uri, { serverApi: { version: ServerApiVersion.v1, strict: true, deprecationErrors: true } }).","If you generated the URI from a config helper, fix the helper so serverApi is excluded from query params."],"exampleFix":"// before\nconst c = new MongoClient('mongodb://host:27017/?serverApi=v1');\n// after\nimport { ServerApiVersion } from 'mongodb';\nconst c = new MongoClient('mongodb://host:27017/', {\n  serverApi: { version: ServerApiVersion.v1, strict: true, deprecationErrors: true }\n});","handlingStrategy":"validation","validationCode":"const u = new URL(uri);\nif (u.searchParams.has('serverApi')) {\n  throw new Error('serverApi must be passed via MongoClient options, not the URI');\n}","typeGuard":null,"tryCatchPattern":"try {\n  client = new MongoClient(uri, opts);\n} catch (e) {\n  if (e instanceof MongoParseError && /serverApi/.test(e.message)) { /* strip serverApi from URI and retry */ }\n  else throw e;\n}","preventionTips":["Keep URI construction and structured options in separate code paths.","Add a unit test that asserts known-good URIs parse without throwing.","Document canonical serverApi setup in your connection helper."],"tags":["connection-string","configuration","stable-api"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}