mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Unable to include driverInfo platform, metadata cannot excee

Error message

Unable to include driverInfo platform, metadata cannot exceed 512 bytes

What it means

Thrown while building client metadata when the platform field (driver runtime info plus any user-supplied driverInfo.platform strings joined with '|') would push the metadata document past the 512-byte BSON limit. Unlike os/env fields which the driver progressively omits to fit, the platform field is explicitly NOT truncated (per the spec comment in the source), so exceeding the limit is a hard error. Surfaced as MongoInvalidArgumentError during the handshake metadata build.

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 3366c21a63)

Solutions

  1. Shorten or remove the driverInfo.platform string(s) contributed by wrappers.
  2. Consolidate multiple platform contributions into one concise value.

Example fix

// before
new MongoClient(uri, { driverInfo: { platform: 'very-long-build-url-or-commit-string'.repeat(20) } });

// after - keep platform concise
new MongoClient(uri, { driverInfo: { platform: 'svc-x' } });
Defensive patterns

Strategy: validation

Validate before calling

// Validate the platform string length before passing it as driverInfo.
function checkPlatform(driverInfoPlatform) {
  const joined = `${getRuntimeInfoStub()}|${driverInfoPlatform ?? ''}`;
  // platform is never truncated; keep total metadata (incl appName/driver/os/env) under 512 bytes.
  if (Buffer.byteLength(joined, 'utf8') > 400) throw new Error('driverInfo.platform too long for 512-byte metadata limit');
}

Try / catch

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

Prevention

When it happens

Trigger: One or more driverInfo entries supply a very long platform string; concatenated with the driver's own runtime info they push the cumulative metadata past 512 bytes after appName, driver, os, and env have been laid out. Because platform is never truncated, a single oversized platform string can trigger this even when other fields are small.

Common situations: Instrumentation/wrapper libraries that inject long platform identifiers (build URLs, commit SHAs, full environment descriptors) via driverInfo.platform. Stacking several such libraries multiplies the length. CI environments that embed long build metadata into platform.

Related errors

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