WebSocketShard: Compression is set to zlib-sync, but it is n

Error message

WebSocketShard: Compression is set to zlib-sync, but it is not installed.

What it means

Warning from WebSocketShard.internalConnect when compression is set to zlib-sync but the optional zlib-sync npm package could not be imported. The shard deletes the 'compress' query parameter so the gateway sends uncompressed data instead of crashing. zlib-sync is an optionalDependency of discord.js and must be installed separately in some setups.

Source

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

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

					break;
				}

				case CompressionMethod.ZstdNative: {
					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);
						});

View on GitHub (pinned to a81ed8a306)

Solutions

Install the package: npm i zlib-sync (it provides prebuilt binaries for common platforms).
Re-enable optional dependencies: remove omit=optional / --ignore-optional and reinstall.
Switch compression to the native zlib method if node:zlib is available in your runtime.
Set compression: null to disable gateway compression entirely.

Example fix

// before
npm install discord.js --ignore-optional
// after
npm install zlib-sync
npm install discord.js

Defensive patterns

Strategy: validation

Validate before calling

let zlibSyncAvailable = false;
try { await import('zlib-sync'); zlibSyncAvailable = true; } catch {}
if (compression === 'zlib-sync' && !zlibSyncAvailable) {
  await import('zlib-sync'); // will throw here with a clear message before connecting
}

Type guard

function isZlibSync(m) { return m != null && typeof m.Inflate === 'function'; }

Try / catch

try {
  await import('zlib-sync');
} catch {
  console.error('zlib-sync requested but not installed: run `npm i zlib-sync`');
  process.exit(1);
}

Prevention

Add zlib-sync as a direct dependency if your code references the zlib-sync compression method.
Do not install with --ignore-optional or omit=optional when you rely on zlib-sync.
Verify the native binding builds in your Docker/CI image (needs toolchain if no prebuilt matches).
Fail fast at boot with an explicit check instead of silently running uncompressed.

When it happens

Trigger: Setting WebSocketShardOptions.compression to the zlib-sync method while zlib-sync is not installed or failed to install (e.g. omitted optional dependencies, --no-optional install flags, native build failures for the zlib-sync prebuilt binding).

Common situations: npm/yarn/pnpm installed with --ignore-optional or omit=optional in .npmrc; environments without build tooling where zlib-sync's native addon failed to compile; Docker slim images; manually curated dependency trees.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

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