mongodb/node-mongodb-native · error · MongoCryptInvalidArgumentError

Cannot set both proxyOptions and kmsConnectCallback

Error message

Cannot set both proxyOptions and kmsConnectCallback

What it means

Thrown by the ClientEncryption constructor when both proxyOptions (with a proxyHost) and kmsConnectCallback are provided. These are mutually exclusive KMS connection mechanisms: proxyOptions sets up a SOCKS5 proxy, while kmsConnectCallback lets you provide a custom socket factory. Only one can be active. This is a MongoCryptInvalidArgumentError.

Solutions

  1. Choose one KMS connection mechanism: either proxyOptions or kmsConnectCallback
  2. For HTTP CONNECT proxies, use kmsConnectCallback and omit proxyOptions
  3. For SOCKS5 proxies, use proxyOptions and omit kmsConnectCallback

Example fix

// before
new ClientEncryption(client, {
  keyVaultNamespace: 'encryption.__keyVault',
  proxyOptions: { proxyHost: 'proxy.example.com', proxyPort: 1080 },
  kmsConnectCallback: myCallback,
  kmsProviders: { ... }
});

// after (choose one)
new ClientEncryption(client, {
  keyVaultNamespace: 'encryption.__keyVault',
  kmsConnectCallback: myCallback,
  kmsProviders: { ... }
});
Defensive patterns

Strategy: validation

Validate before calling

// Before creating ClientEncryption
const { proxyOptions, kmsConnectCallback } = options;
if (proxyOptions?.proxyHost && kmsConnectCallback) {
  throw new Error('Cannot set both proxyOptions and kmsConnectCallback; choose one');
}

Prevention

When it happens

Trigger: Creating a new ClientEncryption instance with options that include both proxyOptions: { proxyHost: '...' } and kmsConnectCallback: fn.

Common situations: Configuring explicit encryption (not auto-encryption) with both proxy mechanisms specified; merging configuration presets that each set one of these options; corporate proxy environments where multiple proxy approaches were attempted.

Related errors

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/54cecab32e49582d. Report an issue: GitHub.

Appendix: source

Thrown at src/client-side-encryption/client_encryption.ts:132

   *
   * @example
   * ```ts
   * new ClientEncryption(mongoClient, {
   *   keyVaultNamespace: 'client.encryption',
   *   kmsProviders: {
   *     aws: {
   *       accessKeyId: AWS_ACCESS_KEY,
   *       secretAccessKey: AWS_SECRET_KEY
   *     }
   *   }
   * });
   * ```
   */
  constructor(client: MongoClient, options: ClientEncryptionOptions) {
    this._client = client;
    this._proxyOptions = options.proxyOptions ?? {};
    if (this._proxyOptions.proxyHost && options.kmsConnectCallback) {
      throw new MongoCryptInvalidArgumentError(
        'Cannot set both proxyOptions and kmsConnectCallback'
      );
    }
    this._tlsOptions = options.tlsOptions ?? {};
    this._kmsConnectCallback = options.kmsConnectCallback;
    this._kmsProviders = options.kmsProviders || {};
    const { timeoutMS } = resolveTimeoutOptions(client, options);
    this._timeoutMS = timeoutMS;
    this._credentialProviders = options.credentialProviders;

    if (options.credentialProviders?.aws && !isEmptyCredentials('aws', this._kmsProviders)) {
      throw new MongoCryptInvalidArgumentError(
        'Can only provide a custom AWS credential provider when the state machine is configured for automatic AWS credential fetching'
      );
    }

    if (options.keyVaultNamespace == null) {
      throw new MongoCryptInvalidArgumentError('Missing required option `keyVaultNamespace`');

View on GitHub (pinned to dce7939f86)