mongodb/node-mongodb-native · error · MongoAPIError

URI option " " cannot be specified with no value

Error message

URI option "${key}" cannot be specified with no value

What it means

Every URI query parameter (except readPreferenceTags, which may legitimately be valueless) must have a value. A key with an empty value, or a '?&key&key2=v' style fragment, yields an empty string in the search params and triggers MongoAPIError.

Solutions

1. Provide an explicit value for every query parameter.
2. Strip keys that should not be set instead of leaving them empty.

Example fix

// before
'mongodb://h/db?tls&appName=foo'
// after
'mongodb://h/db?tls=true&appName=foo'

function assertNoEmptyValues(uri: string) {
  const q = uri.split('?')[1];
  if (!q) return;
  for (const pair of q.split('&')) {
    if (!pair) continue;
    const [key, ...rest] = pair.split('=');
    if (key === 'readPreferenceTags') continue;
    if (rest.length === 0) throw new Error(`URI option '${key}' has no value`);
  }
}

When it happens

Trigger: A URI like 'mongodb://h/db?tls' or 'mongodb://h/db?appName=&retryWrites=true'. Triggered while iterating url.searchParams.keys() when values.includes('').

Common situations: Conditional query-string assembly that leaves a key with no value, trailing '&', or a malformed URI from an env var.

Related errors

• URI option " " cannot appear more than once in the…
• All values of tls/ssl must be the same.
• Auth mechanism property ALLOWED_HOSTS is not allowed in the…
• authMechanism requires an authSource of '$external
• Cannot combine replicaSet option with srvMaxHosts

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/1b2328434a5fe4a9. Report an issue: GitHub.

Appendix: source

Thrown at src/connection_string.ts:298

      auth.password = decodeURIComponent(url.password);
    }

    urlOptions.set('auth', [auth]);
  }

  for (const key of url.searchParams.keys()) {
    const values = url.searchParams.getAll(key);

    const isReadPreferenceTags = /readPreferenceTags/i.test(key);

    if (!isReadPreferenceTags && values.length > 1) {
      throw new MongoInvalidArgumentError(
        `URI option "${key}" cannot appear more than once in the connection string`
      );
    }

    if (!isReadPreferenceTags && values.includes('')) {
      throw new MongoAPIError(`URI option "${key}" cannot be specified with no value`);
    }

    if (!urlOptions.has(key)) {
      urlOptions.set(key, values);
    }
  }

  const objectOptions = new CaseInsensitiveMap<unknown>(
    Object.entries(options).filter(([, v]) => v != null)
  );

  // Validate options that can only be provided by one of uri or object

  if (urlOptions.has('serverApi')) {
    throw new MongoParseError(
      'URI cannot contain `serverApi`, it can only be passed to the client'
    );
  }

View on GitHub (pinned to dce7939f86)