mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Unable to include driverInfo name and version, metadata cann

Error message

Unable to include driverInfo name and version, metadata cannot exceed 512 bytes

What it means

Thrown while building the client metadata document sent in the connection handshake when the driver info (name and version) alone would push the metadata beyond the 512-byte BSON size limit imposed by the MongoDB handshake spec. appName is added first (mandatory, truncated to 128 bytes), then driver name/version; if even that core driver field does not fit, the driver throws MongoInvalidArgumentError. The combined appName + driver name/version (+ any user-supplied driverInfo name/version appended with '|') exceeded 512 bytes.

Source

Thrown at src/cmap/handshake/client_metadata.ts:140

  }

  const driverInfo = {
    name: 'nodejs',
    version: NODE_DRIVER_VERSION
  };

  // This is where we handle additional driver info added after client construction.
  for (const { name: n = '', version: v = '' } of driverInfoList) {
    if (n.length > 0) {
      driverInfo.name = `${driverInfo.name}|${n}`;
    }
    if (v.length > 0) {
      driverInfo.version = `${driverInfo.version}|${v}`;
    }
  }

  if (!metadataDocument.ifItFitsItSits('driver', driverInfo)) {
    throw new MongoInvalidArgumentError(
      'Unable to include driverInfo name and version, metadata cannot exceed 512 bytes'
    );
  }

  let runtimeInfo = getRuntimeInfo();
  // This is where we handle additional driver info added after client construction.
  for (const { platform = '' } of driverInfoList) {
    if (platform.length > 0) {
      runtimeInfo = `${runtimeInfo}|${platform}`;
    }
  }

  if (!metadataDocument.ifItFitsItSits('platform', runtimeInfo)) {
    throw new MongoInvalidArgumentError(
      'Unable to include driverInfo platform, metadata cannot exceed 512 bytes'
    );
  }

View on GitHub (pinned to 3366c21a63)

Solutions

  1. Shorten the appName passed to MongoClient so it is well under 128 bytes.
  2. Reduce the number/length of driverInfo name and version contributions from wrappers; consolidate or shorten them.

Example fix

// before
new MongoClient(uri, { appName: 'x'.repeat(128), driverInfo: { name: 'a'.repeat(300), version: 'b'.repeat(200) } });

// after - keep appName and driverInfo short
new MongoClient(uri, { appName: 'my-app', driverInfo: { name: 'wrapper', version: '1.0' } });
Defensive patterns

Strategy: validation

Validate before calling

// Validate combined driverInfo name+version length before constructing the client.
function checkDriverInfo(appName, driverInfo) {
  const parts = ['nodejs', driverInfo?.name].filter(Boolean);
  const verParts = [DRIVER_VERSION, driverInfo?.version].filter(Boolean);
  const approx = JSON.stringify({ application: { name: appName ?? '' }, driver: { name: parts.join('|'), version: verParts.join('|') } }).length;
  if (approx > 512) throw new Error('appName + driverInfo name/version exceeds 512-byte metadata limit');
}

Try / catch

try {
  const client = new MongoClient(uri, { appName, driverInfo });
  await client.connect();
} catch (err) {
  if (err instanceof MongoInvalidArgumentError && /driverInfo name and version/.test(err.message)) {
    // shorten appName / driverInfo and retry
  }
  throw err;
}

Prevention

When it happens

Trigger: A MongoClient is constructed with a very long appName (up to 128 bytes) plus one or more driverInfo entries whose name/version are extremely long, so that when concatenated as 'nodejs|name1|name2...' / 'version|v1|v2...' the serialized driver subdocument no longer fits in 512 bytes. Each driverInfo entry from instrumentation libraries (APM, OTEL, framework wrappers) appends to both name and version.

Common situations: Multiple wrapping libraries each register driverInfo (e.g. a framework adapter, an OTEL instrumenter, and a custom wrapper), and together their names/versions plus a long appName exceed 512 bytes. Custom driverInfo with an unbounded/buggy value. Heavy instrumentation stacks on top of the driver.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/23dbed48f82af6d1.json. Report an issue: GitHub.