{"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":"validation","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/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/cmap/auth/mongo_credentials.ts#L257-L292","documentation":"Thrown by the MongoCredentials constructor when the GSSAPI (Kerberos) mechanism property CANONICALIZE_HOST_NAME is set to a value that is not one of the allowed GSSAPICanonicalizationValue constants. The allowed values are true, false, 'none', 'forward', or 'forwardAndReverse' (see src/cmap/auth/gssapi.ts:10). This is a client-side configuration validation error surfaced as a MongoAPIError before any network activity occurs.","triggerScenarios":"Connecting with authMechanism=GSSAPI (Kerberos) and providing a malformed authMechanismProperties=CANONICALIZE_HOST_NAME=<value> in the connection string, or passing an invalid value through the credentials' mechanismProperties option. Any value not in {true, false, 'none', 'forward', 'forwardAndReverse'} triggers it during credential merge/construction.","commonSituations":"Typo in the canonicalization value in the URI (e.g. CANONICALIZE_HOST_NAME=truee or =forwardOnly), passing a string 'true'/'false' where the engine still accepts but a totally unknown string does not, or copying a value from documentation for a different driver. Also occurs when mechanismProperties is built programmatically with an unvalidated variable.","solutions":["Set CANONICALIZE_HOST_NAME to one of the exact allowed values: true, false, 'none', 'forward', or 'forwardAndReverse'.","Remove the CANONICALIZE_HOST_NAME property entirely if you do not need host canonicalization; it defaults to false.","If constructing mechanismProperties programmatically, import and use GSSAPICanonicalizationValue from the driver rather than hardcoding strings."],"exampleFix":"// before\nconst client = new MongoClient(\n  'mongodb://user@host/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:yes'\n);\n\n// after\nconst client = new MongoClient(\n  'mongodb://user@host/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:forward'\n);","handlingStrategy":"validation","validationCode":"import { GSSAPICanonicalizationValue } from 'mongodb';\n\nconst allowed = new Set(Object.values(GSSAPICanonicalizationValue));\nfunction isValidCanonicalization(v: unknown): boolean {\n  return allowed.has(v as any);\n}\n\n// before building the connection string\nconst canon = 'forward';\nif (!isValidCanonicalization(canon)) {\n  throw new Error(`Invalid CANONICALIZE_HOST_NAME: ${String(canon)}`);\n}","typeGuard":"import { GSSAPICanonicalizationValue } from 'mongodb';\nconst ALLOWED = new Set<unknown>(Object.values(GSSAPICanonicalizationValue));\nfunction isCanonicalization(v: unknown): v is typeof GSSAPICanonicalizationValue[keyof typeof GSSAPICanonicalizationValue] {\n  return ALLOWED.has(v);\n}","tryCatchPattern":null,"preventionTips":["Always derive CANONICALIZE_HOST_NAME from the exported GSSAPICanonicalizationValue constants, never hardcoded strings.","Omit the property when you do not need canonicalization; default is false.","Validate connection-string authMechanismProperties in a config loader at startup, failing fast with a clear message."],"tags":["auth","gssapi","kerberos","configuration","validation"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}