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

Error message

WebSocketShard: Compression is set to native zlib but node:zlib is not available.

What it means

Warning from WebSocketShard.internalConnect when compression is configured as native zlib (node:zlib-based inflate) but getNativeZlib() returned null — meaning the node:zlib module is unavailable. The shard deletes the 'compress' URL parameter so the gateway sends uncompressed payloads. This only occurs when a compression library/feature was requested but cannot be satisfied in the current runtime.

Source

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

					if (zlib) {
						this.inflateBuffer = [];

						const inflate = zlib.createInflate({
							chunkSize: 65_535,
							flush: zlib.constants.Z_SYNC_FLUSH,
						});

						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 zlib but node:zlib is not available.');
						params.delete('compress');
					}

					break;
				}

				case CompressionMethod.ZlibSync: {
					const zlib = await getZlibSync();
					if (zlib) {
						this.zLibSyncInflate = new zlib.Inflate({
							chunkSize: 65_535,
							to: 'string',
						});
					} else {
						console.warn('WebSocketShard: Compression is set to zlib-sync, but it is not installed.');
						params.delete('compress');
					}

View on GitHub (pinned to a81ed8a306)

Solutions

Use a full Node.js build with zlib support (official Node distributions include node:zlib).
Install and configure zlib-sync instead: npm i zlib-sync and set compression to the zlib-sync method.
Set compression: null to explicitly opt out of gateway compression.
Fix bundler config so node:zlib is external (e.g. 'node-builtins' external in esbuild/webpack), or run in a Node runtime instead of an edge runtime.

Example fix

// before (edge runtime)
export const runtime = 'edge';
// after
export const runtime = 'nodejs'; // node:zlib available

Defensive patterns

Strategy: validation

Validate before calling

let nativeZlibAvailable = false;
try { await import('node:zlib'); nativeZlibAvailable = true; } catch {}
if (compression === 'zlib-native' && !nativeZlibAvailable) {
  compression = null; // or fall back to zlib-sync
}

Type guard

function hasNativeZlib(z) { return z != null && typeof z.createInflate === 'function'; }

Try / catch

try {
  await import('node:zlib');
} catch {
  // runtime lacks node:zlib; disable compression before connecting
  shardOptions.compression = null;
}

Prevention

Deploy on official Node.js builds, not minimal/custom compiles without zlib.
In edge/serverless environments, verify node builtin support before enabling compression.
Check the warn log at startup and fall back to zlib-sync or compression: null.

When it happens

Trigger: Setting WebSocketShardOptions.compression to the native zlib method in an environment where node:zlib cannot be imported (e.g. custom/minimal Node builds compiled without zlib support, edge/serverless runtimes that stub node builtins, bundlers replacing node:zlib with a failing shim).

Common situations: Running discord.js on serverless/edge platforms (Vercel Edge, Cloudflare Workers with node compatibility shims); custom-compiled Node.js without zlib; bundling (webpack/esbuild) misconfiguring node builtins as externals/shims.

Related errors

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