mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Unable to include driverInfo name and version, metadata…

Error message

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

What it means

A MongoInvalidArgumentError thrown in makeClientMetadata when the driver info (name + version) alone cannot fit within the 512-byte BSON limit for client metadata sent during the handshake. The driver first adds application name, then the driver block; if even the driver block overflows 512 bytes, the handshake metadata cannot be constructed and the client refuses to connect.

Solutions

  1. Shorten the driverInfo.name and driverInfo.version strings.
  2. Shorten appName to leave room for driver metadata.
  3. Avoid stacking multiple driverInfo contributors with long identifiers.
  4. Validate driverInfo length at app startup.

Example fix

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

// after
const client = new MongoClient(uri, {
  appName: 'my-app',
  driverInfo: { name: 'my-driver', version: '1.0.0' }
});
Defensive patterns

Strategy: validation

Validate before calling

function byteLength(s: string) { return Buffer.byteLength(s, 'utf8'); }
const total = byteLength(appName) + byteLength(driverInfo.name) + byteLength(driverInfo.version);
if (total > 400) {
  throw new Error('driverInfo + appName too large for 512-byte metadata limit');
}

Prevention

When it happens

Trigger: Providing a driverInfo.name and/or driverInfo.version via MongoClient options whose combined BSON-encoded size (plus application name) exceeds 512 bytes. The driver name accumulates segments like 'nodejs|<yourName>' and version 'x.y.z|<yourVersion>'.

Common situations: Passing very long company/product identifiers in driverInfo.name; long version strings with many segments; a long appName consuming most of the 512-byte budget; multiple middleware layers each appending driverInfo.

Related errors

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

Appendix: 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 dce7939f86)