mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Unknown compressor ${options.agreedCompressor} failed to com

Error message

Unknown compressor ${options.agreedCompressor} failed to compress

What it means

Thrown by the compress() helper when options.agreedCompressor is not one of the supported compressors ('snappy', 'zstd', 'zlib'). The driver and server negotiate a single agreed compressor during the handshake; attempting to compress an outgoing message with any other value is an invalid state. Surfaced as MongoInvalidArgumentError. The agreed compressor should only ever be one of the three supported names (or 'none', which skips compression).

Source

Thrown at src/cmap/wire_protocol/compression.ts:102

    case 'snappy': {
      Snappy ??= loadSnappy();
      return await Snappy.compress(dataToBeCompressed);
    }
    case 'zstd': {
      loadZstd();
      if ('kModuleError' in zstd) {
        throw zstd['kModuleError'];
      }
      return await zstd.compress(dataToBeCompressed, ZSTD_COMPRESSION_LEVEL);
    }
    case 'zlib': {
      if (options.zlibCompressionLevel) {
        zlibOptions.level = options.zlibCompressionLevel;
      }
      return await zlibDeflate(dataToBeCompressed, zlibOptions);
    }
    default: {
      throw new MongoInvalidArgumentError(
        `Unknown compressor ${options.agreedCompressor} failed to compress`
      );
    }
  }
}

// Decompress a message using the given compressor
export async function decompress(
  compressorID: number,
  compressedData: Uint8Array
): Promise<Uint8Array> {
  if (
    compressorID !== Compressor.snappy &&
    compressorID !== Compressor.zstd &&
    compressorID !== Compressor.zlib &&
    compressorID !== Compressor.none
  ) {
    throw new MongoDecompressionError(

View on GitHub (pinned to 3366c21a63)

Solutions

1. Use only supported compressors in the connection string: `?compressors=zlib` or `?compressors=zstd` or `?compressors=snappy`.
2. If you pass a description/agreedCompressor programmatically, ensure it is one of 'snappy','zstd','zlib'.
3. Remove the compressors option entirely to disable compression and confirm the error disappears, then re-add a valid value.

Example fix

// before
new MongoClient('mongodb://host/?compressors=lz4'); // unsupported

// after
new MongoClient('mongodb://host/?compressors=zlib');

const VALID_COMPRESSORS = new Set(['none', 'snappy', 'zlib', 'zstd']);
function validateCompressors(uri) {
  const c = new URL(uri).searchParams.get('compressors');
  if (c) for (const part of c.split(',')) if (!VALID_COMPRESSORS.has(part.toLowerCase())) throw new Error(`Unsupported compressor: ${part}`);
}
validateCompressors(process.env.MONGODB_URI);

When it happens

Trigger: compress() is called with an agreedCompressor value outside the snappy/zstd/zlib set. This is normally driven internally by the negotiated compressor from the handshake; a user trigger requires manually passing a bad compressor into compressCommand description, or corrupting the compressor negotiation. Most often reflects a bug or a tampered options object rather than normal use.

Common situations: Passing a custom/typo'd compressor string in the connection string `compressors=zlibb`. A wrapper that overwrites the agreed compressor on the connection description. Future/unsupported compressor names not recognized by the installed driver version.

Related errors

• Server sent message compressed using an unsupported compress
• Message body and message header must be the same length
• compressors must be an array or a comma-delimited list of st
• ${c} is not a valid compression mechanism. Must be one of: $
• Cannot set both proxyOptions and kmsConnectCallback

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