WebSocketShard: Identify compression is enabled, but node:zl

Error message

WebSocketShard: Identify compression is enabled, but node:zlib is not available.

What it means

Warning from WebSocketShard.internalConnect when useIdentifyCompression is true but getNativeZlib() returned null, so node:zlib is unavailable to compress the identify payload. The shard sets identifyCompressionEnabled = false and connects without identify compression, trading some bandwidth for compatibility. This mirrors error 341 but scoped to the identify (payload) compression option rather than transport compression.

Source

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

						});

						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;
			}
		}

		const session = await this.strategy.retrieveSessionInfo(this.id);

		const url = `${session?.resumeURL ?? this.strategy.options.gatewayInformation.url}?${params.toString()}`;

		this.debug([`Connecting to ${url}`]);

		const connection = new WebSocketConstructor(url, [], {
			handshakeTimeout: this.strategy.options.handshakeTimeout ?? undefined,
		});

		connection.binaryType = 'arraybuffer';

		connection.onmessage = (event) => {
			void this.onMessage(event.data, event.data instanceof ArrayBuffer);

View on GitHub (pinned to a81ed8a306)

Solutions

Run on a standard Node.js build where node:zlib is present.
Fix bundler/runtime config so node:zlib resolves to the real Node builtin (mark as external; use the nodejs runtime).
Set useIdentifyCompression: false explicitly if the environment cannot support it.
Ignore the warning if the automatic fallback to uncompressed identify is acceptable.

Example fix

// before
new WebSocketShard({
  useIdentifyCompression: true, // requires node:zlib
});
// after (unsupported runtime)
new WebSocketShard({
  useIdentifyCompression: false,
});

Defensive patterns

Strategy: validation

Validate before calling

let nativeZlibAvailable = false;
try { await import('node:zlib'); nativeZlibAvailable = true; } catch {}
if (useIdentifyCompression && !nativeZlibAvailable) {
  useIdentifyCompression = false; // avoids the warning and silent downgrade
}

Type guard

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

Try / catch

try {
  await import('node:zlib');
} catch {
  // no node:zlib in this runtime; disable identify compression up front
  shardOptions.useIdentifyCompression = false;
}

Prevention

Only enable useIdentifyCompression on standard Node.js runtimes.
Set useIdentifyCompression: false explicitly in edge/serverless deployments.
Run a startup capability check (node:zlib import) before constructing the manager.
Keep identify compression off unless large identify payloads are a measured problem.

When it happens

Trigger: Setting useIdentifyCompression: true in WebSocketShardOptions/WebSocketManager options in an environment where node:zlib cannot be loaded (custom Node builds without zlib, edge runtimes, broken bundler shims).

Common situations: Hosting discord.js in edge/serverless runtimes; minimal Docker images or alpine builds with stripped Node; bundling node:zlib incorrectly; custom Node compiled --without-zlib (shared) library.

Related errors

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