{"id":"23dbed48f82af6d1","repo":"mongodb/node-mongodb-native","slug":"unable-to-include-driverinfo-name-and-version-met","errorCode":null,"errorMessage":"Unable to include driverInfo name and version, metadata cannot exceed 512 bytes","messagePattern":"Unable to include driverInfo name and version, metadata cannot exceed 512 bytes","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/cmap/handshake/client_metadata.ts","lineNumber":140,"sourceCode":"  }\n\n  const driverInfo = {\n    name: 'nodejs',\n    version: NODE_DRIVER_VERSION\n  };\n\n  // This is where we handle additional driver info added after client construction.\n  for (const { name: n = '', version: v = '' } of driverInfoList) {\n    if (n.length > 0) {\n      driverInfo.name = `${driverInfo.name}|${n}`;\n    }\n    if (v.length > 0) {\n      driverInfo.version = `${driverInfo.version}|${v}`;\n    }\n  }\n\n  if (!metadataDocument.ifItFitsItSits('driver', driverInfo)) {\n    throw new MongoInvalidArgumentError(\n      'Unable to include driverInfo name and version, metadata cannot exceed 512 bytes'\n    );\n  }\n\n  let runtimeInfo = getRuntimeInfo();\n  // This is where we handle additional driver info added after client construction.\n  for (const { platform = '' } of driverInfoList) {\n    if (platform.length > 0) {\n      runtimeInfo = `${runtimeInfo}|${platform}`;\n    }\n  }\n\n  if (!metadataDocument.ifItFitsItSits('platform', runtimeInfo)) {\n    throw new MongoInvalidArgumentError(\n      'Unable to include driverInfo platform, metadata cannot exceed 512 bytes'\n    );\n  }\n","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/handshake/client_metadata.ts#L122-L158","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Shorten the appName passed to MongoClient so it is well under 128 bytes.","Reduce the number/length of driverInfo name and version contributions from wrappers; consolidate or shorten them."],"exampleFix":"// before\nnew MongoClient(uri, { appName: 'x'.repeat(128), driverInfo: { name: 'a'.repeat(300), version: 'b'.repeat(200) } });\n\n// after - keep appName and driverInfo short\nnew MongoClient(uri, { appName: 'my-app', driverInfo: { name: 'wrapper', version: '1.0' } });","handlingStrategy":"validation","validationCode":"// Validate combined driverInfo name+version length before constructing the client.\nfunction checkDriverInfo(appName, driverInfo) {\n  const parts = ['nodejs', driverInfo?.name].filter(Boolean);\n  const verParts = [DRIVER_VERSION, driverInfo?.version].filter(Boolean);\n  const approx = JSON.stringify({ application: { name: appName ?? '' }, driver: { name: parts.join('|'), version: verParts.join('|') } }).length;\n  if (approx > 512) throw new Error('appName + driverInfo name/version exceeds 512-byte metadata limit');\n}","typeGuard":null,"tryCatchPattern":"try {\n  const client = new MongoClient(uri, { appName, driverInfo });\n  await client.connect();\n} catch (err) {\n  if (err instanceof MongoInvalidArgumentError && /driverInfo name and version/.test(err.message)) {\n    // shorten appName / driverInfo and retry\n  }\n  throw err;\n}","preventionTips":["Keep appName short (well under 128 bytes).","Limit the number and length of driverInfo name/version contributions from wrappers.","Consolidate multiple wrapper driverInfo entries."],"tags":["handshake","client-metadata","configuration","size-limit"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}