mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Unable to include driverInfo platform, metadata cannot…

Error message

Unable to include driverInfo platform, metadata cannot exceed 512 bytes

What it means

A MongoInvalidArgumentError thrown in makeClientMetadata when the platform string (runtime info + custom driverInfo.platform segments) cannot fit within the 512-byte metadata limit after application and driver blocks were added. The platform field accumulates runtime info like 'Node.js vXX, LE' plus any user-supplied driverInfo.platform values joined with '|'.

Solutions

  1. Shorten driverInfo.platform values.
  2. Shorten appName to leave room.
  3. Consolidate multiple platform contributors.
  4. Validate total metadata size at startup.

Example fix

// before
const client = new MongoClient(uri, {
  driverInfo: { platform: 'P'.repeat(500) }
});

// after
const client = new MongoClient(uri, {
  driverInfo: { platform: 'edge-region-eu' }
});
Defensive patterns

Strategy: validation

Validate before calling

const platformBytes = Buffer.byteLength(driverInfo.platform ?? '', 'utf8');
if (platformBytes > 200) {
  throw new Error('driverInfo.platform too large for 512-byte metadata limit');
}

Prevention

When it happens

Trigger: Supplying a long driverInfo.platform string, or multiple driverInfo contributors with platform segments, such that the total BSON metadata exceeds 512 bytes once driver and app name are included.

Common situations: Embedding long diagnostic/architecture tags in driverInfo.platform; multiple libraries each appending platform metadata; long appName compounding the overflow.

Related errors

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

Appendix: source

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

    }
  }

  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'
    );
  }

  // Note: order matters, os.type is last so it will be removed last if we're at maxSize
  const osInfo = new Map()
    .set('name', os.platform())
    .set('architecture', os.arch())
    .set('version', os.release())
    .set('type', os.type());

  if (!metadataDocument.ifItFitsItSits('os', osInfo)) {
    for (const key of osInfo.keys()) {
      osInfo.delete(key);
      if (osInfo.size === 0) break;
      if (metadataDocument.ifItFitsItSits('os', osInfo)) break;
    }
  }

View on GitHub (pinned to dce7939f86)