clockworklabs/SpacetimeDB · error · Error

Unexpected Compression Algorithm. Please use `gzip` or `none

Error message

Unexpected Compression Algorithm. Please use `gzip` or `none`

What it means

Thrown by the SDK's WebSocket decompression adapter (WebsocketDecompressAdapter#decompress) while unwrapping an incoming server frame. Every frame starts with a one-byte compression tag negotiated at subscribe time: 0 = none, 1 = brotli, 2 = gzip; any other tag hits the default branch. Despite the message text mentioning only gzip/none, brotli is supported too, so the real meaning is: the server sent a compression tag this SDK build does not recognize.

Source

Thrown at crates/bindings-typescript/src/sdk/websocket_decompress_adapter.ts:59

  }

  #ws: WebSocket;

  async #decompress(buffer: Uint8Array<ArrayBuffer>): Promise<Uint8Array> {
    const tag = buffer[0];
    const data = buffer.subarray(1);
    switch (tag) {
      case 0:
        return data;
      case 1:
        // Some runtimes support brotli, but it's not yet defined in `lib.dom.d.ts`.
        // We assert runtime support in `DbConnectionBuilder.withCompression`, so
        // this cast is safe.
        return await decompress(data, 'brotli' as CompressionFormat);
      case 2:
        return await decompress(data, 'gzip');
      default:
        throw new Error(
          'Unexpected Compression Algorithm. Please use `gzip` or `none`'
        );
    }
  }

  send(msg: Uint8Array<ArrayBuffer>): void {
    this.#ws.send(msg);
  }

  close(): void {
    this.#ws.close();
  }

  constructor(ws: WebSocket) {
    this.#ws = ws;
  }

  static async openWebSocket(

View on GitHub (pinned to 524b4487d9)

Solutions

1. Align versions: upgrade the TypeScript SDK to match the spacetimedb server version (or downgrade the server) so both agree on the compression tags
2. As a workaround, build the connection with .withCompression('none') so the server sends tag 0 and payloads pass through untouched
3. Remove or bypass any proxy/middleware between client and server that could rewrite binary WebSocket frames
4. If you inject a custom WebSocketFactory, verify it hands the SDK the raw, unmodified frame bytes

Example fix

// before
const db = DbConnection.builder()
  .withUri('ws://localhost:3000')
  .withModuleName('my_module')
  .build(); // server uses a compression tag this SDK doesn't know

// after: pin compression to 'none' until SDK and server versions match
const db = DbConnection.builder()
  .withUri('ws://localhost:3000')
  .withModuleName('my_module')
  .withCompression('none')
  .build();

The adapter already converts this into console.error('[SpacetimeDB] WebSocket decompress failed, closing socket:', e) plus a socket close, so catch it in your onDisconnect handler: on close with that console signature or an abnormal close code, either rebuild the connection with .withCompression('none') or stop retrying and prompt an SDK upgrade.

When it happens

Trigger: A spacetimedb server newer than the client SDK emits frames with a tag >= 3 (a compression algorithm the old SDK predates), or a proxy / custom WebSocketFactory delivers a buffer whose first byte was shifted or corrupted, so the switch in websocket_decompress_adapter.ts falls through to default.

Common situations: Upgrading the spacetimedb host while the app pins an older @clockworklabs SDK; middleware (corporate proxies, CDIs) rewriting binary WebSocket frames; hand-rolled WebSocket adapters in tests feeding misaligned ArrayBuffers. Note the adapter catches this error, logs '[SpacetimeDB] WebSocket decompress failed, closing socket:' and closes the socket, so users usually see it as a disconnect loop with that console error.

Related errors

• Brotli compression is not supported by the runtime. Please c
• v3 websocket payloads must contain at least one message
• Unknown compression type
• cannot serialize refs without a typespace
• cannot deserialize refs without a typespace

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/f760db2fc3b4300e. Report an issue: GitHub.