What causes "compressors must be an array or a comma-delimited list of strings" in mongodb/node-mongodb-native?

Pass an array: `new MongoClient(uri, { compressors: ['zlib'] })`.

mongodb/node-mongodb-native · error · MongoInvalidArgumentError

compressors must be an array or a comma-delimited list of…

Error message

compressors must be an array or a comma-delimited list of strings

What it means

The `compressors` connection option accepts either an array of compressor names (e.g. ['zlib','snappy']) or a single comma-delimited string (e.g. 'zlib,snappy'). The transform at src/connection_string.ts:780 first splits a string on commas, otherwise uses the value as-is; if that result is not an Array, the driver throws MongoInvalidArgumentError at src/connection_string.ts:785. This guard rejects values whose type the option can never consume (numbers, booleans, plain objects).

Solutions

Pass an array: `new MongoClient(uri, { compressors: ['zlib'] })`.
Or pass a comma-delimited string: `new MongoClient(uri, { compressors: 'zlib,snappy' })`.
Inspect the source of the value (env var / config loader) and coerce it to a string or array before passing it to MongoClient.

Example fix

// before
new MongoClient(uri, { compressors: 1 });

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

Defensive patterns

Strategy: type-guard

Validate before calling

function isValidCompressorsInput(v: unknown): boolean {
  return typeof v === 'string' || Array.isArray(v);
}
if (!isValidCompressorsInput(opts.compressors)) {
  throw new Error('compressors must be a string or array');
}

Type guard

function isCompressorsInput(v: unknown): v is string | unknown[] {
  return typeof v === 'string' || Array.isArray(v);
}

Try / catch

try { client = new MongoClient(uri, opts); } catch (e) { if (e instanceof MongoInvalidArgumentError && /compressors/.test(e.message)) { /* fix opts */ } else throw e; }

Prevention

Type the options object as MongoClientOptions so the compiler rejects wrong types.
When reading from env/config, coerce the value to a string before passing it in.
Add a unit test that constructs MongoClient with your production config object.

When it happens

Trigger: Calling `new MongoClient(uri, { compressors: 1 })`, `new MongoClient(uri, { compressors: true })`, `new MongoClient(uri, { compressors: { zlib: true } })`, or `new MongoClient('mongodb://host?compressors=...')` with a value that is neither an array nor a string. The error is thrown during MongoClient construction while the options table transforms are applied.

Common situations: Loading `compressors` from an environment variable or JSON config that decodes to a non-string/non-array type (e.g. a number flag, a feature-toggle object); downstream tooling injecting the wrong type; copy-pasting a comma string but accidentally wrapping it as another type.

Related errors

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

Appendix: source

Thrown at src/connection_string.ts:785

            ServerApiVersion
          ).join('", "')}"]`
        );
      }
      return serverApiToValidate;
    }
  },
  checkKeys: {
    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];
    }
  },

View on GitHub (pinned to dce7939f86)