{"id":"1b2328434a5fe4a9","repo":"mongodb/node-mongodb-native","slug":"uri-option-key-cannot-be-specified-with-no-va","errorCode":null,"errorMessage":"URI option \"${key}\" cannot be specified with no value","messagePattern":"URI option \"(.+?)\" cannot be specified with no value","errorType":"exception","errorClass":"MongoAPIError","httpStatus":null,"severity":"error","filePath":"src/connection_string.ts","lineNumber":298,"sourceCode":"      auth.password = decodeURIComponent(url.password);\n    }\n\n    urlOptions.set('auth', [auth]);\n  }\n\n  for (const key of url.searchParams.keys()) {\n    const values = url.searchParams.getAll(key);\n\n    const isReadPreferenceTags = /readPreferenceTags/i.test(key);\n\n    if (!isReadPreferenceTags && values.length > 1) {\n      throw new MongoInvalidArgumentError(\n        `URI option \"${key}\" cannot appear more than once in the connection string`\n      );\n    }\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  }","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/connection_string.ts#L280-L316","documentation":"Thrown during option parsing when a URI query parameter is present with an empty value (e.g. ?retryWrites=), except for readPreferenceTags. The driver collects values via getAll(key) and rejects any key whose value list contains the empty string. It is a MongoAPIError raised while scanning url.searchParams.","triggerScenarios":"URI like mongodb://h/db?appname= or ?retryWrites=&tls=true; templating an option from an unset env var producing 'key='; URL builders that append 'key=' when the value is empty; trailing '&' creating an empty segment.","commonSituations":"Interpolating optional env vars into the URI without omitting the key when unset; copy-paste leaving a placeholder value blank; URI builders that always append a key even when the value is missing.","solutions":["Omit the key entirely when the value is empty rather than emitting 'key='.","Filter out empty-value params before assembling the URI.","Prefer the options object for optional settings so absent = unset.","Validate the final URI with new URL(uri) and assert no searchParam value is ''."],"exampleFix":"// before\nconst uri = `mongodb://h/db?appname=${process.env.APP_NAME}`; // empty -> 'appname='\n// after\nconst params = new URLSearchParams();\nif (process.env.APP_NAME) params.set('appname', process.env.APP_NAME);\nconst uri = `mongodb://h/db${params.toString() ? '?' + params : ''}`;","handlingStrategy":"validation","validationCode":"function dropEmptyParams(uri: string): string {\n  const [base, query] = uri.split('?');\n  if (!query) return uri;\n  const params = new URLSearchParams();\n  for (const [k, v] of new URLSearchParams(query).entries()) {\n    if (v !== '') params.append(k, v);\n  }\n  const qs = params.toString();\n  return qs ? `${base}?${qs}` : base;\n}","typeGuard":"const hasNoEmptyParams = (uri: string): boolean => {\n  const q = uri.split('?')[1];\n  if (!q) return true;\n  for (const [, v] of new URLSearchParams(q).entries()) {\n    if (v === '') return false;\n  }\n  return true;\n};","tryCatchPattern":"try {\n  await client.connect();\n} catch (e) {\n  if (e instanceof MongoAPIError && /cannot be specified with no value/.test(e.message)) {\n    return new MongoClient(dropEmptyParams(uri)).connect();\n  }\n  throw e;\n}","preventionTips":["Omit optional keys entirely when their value is empty.","Build URIs with URLSearchParams and only set non-empty values.","Validate the final URI has no empty-valued params before connect."],"tags":["connection-string","parsing","config","uri"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}