WebSocketShard: Compression is set to native zstd but node:z

Error message

WebSocketShard: Compression is set to native zstd but node:zlib is not available or your node version does not support zstd decompression.

What it means

Warning from WebSocketShard.internalConnect when compression is set to native zstd but either node:zlib is unavailable or the running Node.js version lacks zstd decompression support (zstd was added to node:zlib in Node 23.8+/22.15+). The shard deletes the 'compress' parameter so the gateway sends uncompressed payloads. This prevents a crash from calling a nonexistent zlib.createZstd... API.

Source

Thrown at packages/ws/src/ws/WebSocketShard.ts:260

					const zlib = await getNativeZlib();
					if (zlib && 'createZstdDecompress' in zlib) {
						this.inflateBuffer = [];

						const inflate = zlib.createZstdDecompress({
							chunkSize: 65_535,
						}) as nativeZlib.Inflate;

						inflate.on('data', (chunk) => {
							this.inflateBuffer.push(chunk);
						});

						inflate.on('error', (error) => {
							this.emit(WebSocketShardEvents.Error, error);
						});

						this.nativeInflate = inflate;
					} else {
						console.warn(
							'WebSocketShard: Compression is set to native zstd but node:zlib is not available or your node version does not support zstd decompression.',
						);
						params.delete('compress');
					}

					break;
				}
			}
		}

		if (this.identifyCompressionEnabled) {
			const zlib = await getNativeZlib();
			if (!zlib) {
				console.warn('WebSocketShard: Identify compression is enabled, but node:zlib is not available.');
				this.identifyCompressionEnabled = false;
			}
		}

View on GitHub (pinned to a81ed8a306)

Solutions

Upgrade Node.js to a version with zlib zstd support (Node 23.8+, or 22.15+ with the backport; check zlib/zstd availability).
Fall back to zlib-stream transport compression or zlib-sync until the runtime supports zstd.
Set compression: null to disable compression.
Add an engine/runtime check in CI (e.g. engines.node) so zstd compression is only used on supported Node versions.

Example fix

// before
"engines": { "node": ">=18" }
// after
"engines": { "node": ">=23.8 || >=22.15" } // zlib zstd support required for CompressionMethod.ZstdNative

Defensive patterns

Strategy: fallback

Validate before calling

let zstdSupported = false;
try {
  const zlib = await import('node:zlib');
  zstdSupported = typeof zlib.createZstdDecompress === 'function' || typeof zlib.zstdDecompress === 'function';
} catch {}
if (compression === 'zstd-native' && !zstdSupported) {
  compression = 'zlib-stream'; // graceful fallback
}

Type guard

function supportsZstd(z) { return z != null && (typeof z.createZstdDecompress === 'function' || typeof z.zstdDecompressSync === 'function'); }

Try / catch

try {
  const zlib = await import('node:zlib');
  if (!supportsZstd(zlib)) throw new Error('no zstd');
} catch {
  shardOptions.compression = CompressionMethod.ZlibStream; // or null
}

Prevention

Pin Node >=23.8 (or >=22.15) when using native zstd compression.
Encode minimum Node version in engines and verify in CI before enabling zstd.
Prefer zlib-stream/zlib-sync in mixed-fleet deployments where Node versions differ.
Monitor for this warning and treat it as a prompt to upgrade the runtime.

When it happens

Trigger: Setting WebSocketShardOptions.compression to the native zstd method while running a Node.js version whose zlib has no Zstandard support, or in runtimes where node:zlib cannot be loaded at all.

Common situations: Running Node 18/20/22.x (pre-22.15) or any LTS older than the zstd additions; Docker images pinned to older Node; users opting into the newest gateway compression before upgrading Node.

Related errors

AI-assisted analysis of discordjs/discord.js@a81ed8a306 (2026-08-30). Data as JSON: /api/errors/602c7f617bcf6315. Report an issue: GitHub.