mongodb/node-mongodb-native · error · MongoInvalidArgumentError

is not a valid compression mechanism. Must be one of: .

Error message

${c} is not a valid compression mechanism. Must be one of: ${Object.keys(Compressor)}.

What it means

After accepting the compressors value, the transform iterates each entry and checks `Object.keys(Compressor).includes(String(c))` at src/connection_string.ts:790. The Compressor object is frozen at src/cmap/wire_protocol/compression.ts:18 with keys `none`, `snappy`, `zlib`, `zstd`. Any entry that is not one of those names triggers MongoInvalidArgumentError at src/connection_string.ts:793 with a message listing the valid keys.

Solutions

Use only one of: `none`, `snappy`, `zlib`, `zstd`.
If you need `snappy` or `zstd`, also install the optional package (`snappy`, `@mongodb-js/zstd`).
Spell the name exactly as in the Compressor object (lowercase, no hyphens).

Example fix

// before
new MongoClient(uri, { compressors: ['gzip'] });

// after
new MongoClient(uri, { compressors: ['zlib'] });

Defensive patterns

Strategy: validation

Validate before calling

import { Compressor } from 'mongodb';
const VALID = Object.keys(Compressor); // ['none','snappy','zlib','zstd']
const list = typeof opts.compressors === 'string' ? opts.compressors.split(',') : (opts.compressors as any[] ?? []);
for (const c of list) {
  if (!VALID.includes(String(c))) throw new Error(`invalid compressor: ${c}`);
}

Type guard

function isCompressorName(v: unknown, valid: string[]): v is string { return typeof v === 'string' && valid.includes(v); }

Try / catch

try { client = new MongoClient(uri, opts); } catch (e) { if (e instanceof MongoInvalidArgumentError && /compression mechanism/.test(e.message)) { /* remove the bad name */ } else throw e; }

Prevention

Restrict the compressor list to a constant derived from Object.keys(Compressor).
Install optional deps (snappy, @mongodb-js/zstd) when you reference them.
Avoid 'none' in the array — it disables compression by name.

When it happens

Trigger: Passing `compressors: ['gzip']`, `compressors: ['lz4']`, `compressors: 'brotli'`, or `?compressors=gzip` in the URI. The check runs per-entry, so the offending name is interpolated into the message.

Common situations: Confusing MongoDB wire-protocol compressors with HTTP content-encoding names; typos like 'z-lib' or 'snappy4'; assuming a system-installed codec name is accepted. Note `snappy` and `zstd` are optional peer dependencies and must also be installed, but a missing dependency surfaces as a different error — this error is purely about the name.

Related errors

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

Appendix: source

Thrown at src/connection_string.ts:793

    type: 'boolean'
  },
  compressors: {
    default: 'none',
    target: 'compressors',
    transform({ values }) {
      const compressionList = new Set();
      for (const compVal of values as (CompressorName[] | string)[]) {
        const compValArray = typeof compVal === 'string' ? compVal.split(',') : compVal;
        if (!Array.isArray(compValArray)) {
          throw new MongoInvalidArgumentError(
            'compressors must be an array or a comma-delimited list of strings'
          );
        }
        for (const c of compValArray) {
          if (Object.keys(Compressor).includes(String(c))) {
            compressionList.add(String(c));
          } else {
            throw new MongoInvalidArgumentError(
              `${c} is not a valid compression mechanism. Must be one of: ${Object.keys(
                Compressor
              )}.`
            );
          }
        }
      }
      return [...compressionList];
    }
  },
  connectTimeoutMS: {
    default: 30000,
    type: 'uint'
  },
  dbName: {
    type: 'string'
  },
  directConnection: {

View on GitHub (pinned to dce7939f86)