{"record":{"id":"bdcbcf69852b599a","repo":"mongodb/node-mongodb-native","slug":"invalid-canonicalize-host-name-value-canonicali","errorCode":null,"errorMessage":"Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}","messagePattern":"Invalid CANONICALIZE_HOST_NAME value: (.+?)","errorType":"exception","errorClass":"MongoAPIError","httpStatus":null,"severity":"error","filePath":"src/cmap/auth/mongo_credentials.ts","lineNumber":275,"sourceCode":"    }\n\n    if (this.mechanism === AuthMechanism.MONGODB_PLAIN && this.source == null) {\n      // TODO(NODE-3485): Replace this with a MongoAuthValidationError\n      throw new MongoAPIError('PLAIN Authentication Mechanism needs an auth source');\n    }\n\n    if (this.mechanism === AuthMechanism.MONGODB_X509 && this.password != null) {\n      if (this.password === '') {\n        Reflect.set(this, 'password', undefined);\n        return;\n      }\n      // TODO(NODE-3485): Replace this with a MongoAuthValidationError\n      throw new MongoAPIError(`Password not allowed for mechanism MONGODB-X509`);\n    }\n\n    const canonicalization = this.mechanismProperties.CANONICALIZE_HOST_NAME ?? false;\n    if (!Object.values(GSSAPICanonicalizationValue).includes(canonicalization)) {\n      throw new MongoAPIError(`Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}`);\n    }\n  }\n\n  static merge(\n    creds: MongoCredentials | undefined,\n    options: Partial<MongoCredentialsOptions>\n  ): MongoCredentials {\n    return new MongoCredentials({\n      username: options.username ?? creds?.username ?? '',\n      password: options.password ?? creds?.password ?? '',\n      mechanism: options.mechanism ?? creds?.mechanism ?? AuthMechanism.MONGODB_DEFAULT,\n      mechanismProperties: options.mechanismProperties ?? creds?.mechanismProperties ?? {},\n      source: options.source ?? options.db ?? creds?.source ?? 'admin'\n    });\n  }\n}\n","sourceCodeStart":257,"sourceCodeEnd":292,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/cmap/auth/mongo_credentials.ts#L257-L292","documentation":"Thrown by MongoCredentials.validate() when CANONICALIZE_HOST_NAME has a value not in the allowed set. Allowed values are: true ('on'), false ('off'), 'none', 'forward', 'forwardAndReverse'. This property controls GSSAPI/Kerberos hostname canonicalization and an unrecognized value is rejected before any auth attempt.","triggerScenarios":"Setting authMechanismProperties.CANONICALIZE_HOST_NAME to a string or value outside the allowed set while using GSSAPI (or any mechanism, since the check runs for all). Fires at validate() line 274.","commonSituations":"Typing 'true'/'false' as strings in code (string 'true' is not boolean true). Using values like 'yes'/'no'/'both'. Confusing the boolean and string forms of the option.","solutions":["Use one of: true, false, 'none', 'forward', 'forwardAndReverse'.","If passing via connection string, use the canonical lowercase token (e.g. CANONICALIZE_HOST_NAME:forward).","In JS code, pass the actual boolean true/false, not the strings 'true'/'false'."],"exampleFix":"// before\nmechanismProperties: { CANONICALIZE_HOST_NAME: 'yes' }\n// after\nmechanismProperties: { CANONICALIZE_HOST_NAME: 'forward' }","handlingStrategy":"type-guard","validationCode":"const ALLOWED = [true,false,'none','forward','forwardAndReverse'];\nfunction assertCanonicalize(v) {\n  if (!ALLOWED.includes(v)) throw new Error('Invalid CANONICALIZE_HOST_NAME');\n}","typeGuard":"function isCanonicalizeValue(v): v is boolean|'none'|'forward'|'forwardAndReverse' {\n  return [true,false,'none','forward','forwardAndReverse'].includes(v);\n}","tryCatchPattern":null,"preventionTips":["Pass booleans as actual booleans, not strings, in JS code.","Restrict the option in your config schema to the allowed literals.","Prefer the string forms for clarity in connection strings."],"tags":["authentication","gssapi","kerberos","configuration","validation"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}