mongodb/node-mongodb-native · error · MongoAPIError

Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}

Error message

Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}

What it means

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.

Source

Thrown at src/cmap/auth/mongo_credentials.ts:275

    }

    if (this.mechanism === AuthMechanism.MONGODB_PLAIN && this.source == null) {
      // TODO(NODE-3485): Replace this with a MongoAuthValidationError
      throw new MongoAPIError('PLAIN Authentication Mechanism needs an auth source');
    }

    if (this.mechanism === AuthMechanism.MONGODB_X509 && this.password != null) {
      if (this.password === '') {
        Reflect.set(this, 'password', undefined);
        return;
      }
      // TODO(NODE-3485): Replace this with a MongoAuthValidationError
      throw new MongoAPIError(`Password not allowed for mechanism MONGODB-X509`);
    }

    const canonicalization = this.mechanismProperties.CANONICALIZE_HOST_NAME ?? false;
    if (!Object.values(GSSAPICanonicalizationValue).includes(canonicalization)) {
      throw new MongoAPIError(`Invalid CANONICALIZE_HOST_NAME value: ${canonicalization}`);
    }
  }

  static merge(
    creds: MongoCredentials | undefined,
    options: Partial<MongoCredentialsOptions>
  ): MongoCredentials {
    return new MongoCredentials({
      username: options.username ?? creds?.username ?? '',
      password: options.password ?? creds?.password ?? '',
      mechanism: options.mechanism ?? creds?.mechanism ?? AuthMechanism.MONGODB_DEFAULT,
      mechanismProperties: options.mechanismProperties ?? creds?.mechanismProperties ?? {},
      source: options.source ?? options.db ?? creds?.source ?? 'admin'
    });
  }
}

View on GitHub (pinned to 3366c21a63)

Solutions

1. Set CANONICALIZE_HOST_NAME to one of the exact allowed values: true, false, 'none', 'forward', or 'forwardAndReverse'.
2. Remove the CANONICALIZE_HOST_NAME property entirely if you do not need host canonicalization; it defaults to false.
3. If constructing mechanismProperties programmatically, import and use GSSAPICanonicalizationValue from the driver rather than hardcoding strings.

Example fix

// before
const client = new MongoClient(
  'mongodb://user@host/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:yes'
);

// after
const client = new MongoClient(
  'mongodb://user@host/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:mongodb,CANONICALIZE_HOST_NAME:forward'
);

import { GSSAPICanonicalizationValue } from 'mongodb';

const allowed = new Set(Object.values(GSSAPICanonicalizationValue));
function isValidCanonicalization(v: unknown): boolean {
  return allowed.has(v as any);
}

// before building the connection string
const canon = 'forward';
if (!isValidCanonicalization(canon)) {
  throw new Error(`Invalid CANONICALIZE_HOST_NAME: ${String(canon)}`);
}

import { GSSAPICanonicalizationValue } from 'mongodb';
const ALLOWED = new Set<unknown>(Object.values(GSSAPICanonicalizationValue));
function isCanonicalization(v: unknown): v is typeof GSSAPICanonicalizationValue[keyof typeof GSSAPICanonicalizationValue] {
  return ALLOWED.has(v);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Credentials required for GSSAPI authentication
• Invalid source '${this.source}' for mechanism '${this.mechan
• TOKEN_RESOURCE must be set in the auth mechanism properties
• User provided OIDC callbacks must return a valid object with
• TOKEN_RESOURCE must be set in the auth mechanism properties

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