{"record":{"id":"f760db2fc3b4300e","repo":"clockworklabs/SpacetimeDB","slug":"unexpected-compression-algorithm-please-use-gzip","errorCode":null,"errorMessage":"Unexpected Compression Algorithm. Please use `gzip` or `none`","messagePattern":"Unexpected Compression Algorithm\\. Please use `gzip` or `none`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/sdk/websocket_decompress_adapter.ts","lineNumber":59,"sourceCode":"  }\n\n  #ws: WebSocket;\n\n  async #decompress(buffer: Uint8Array<ArrayBuffer>): Promise<Uint8Array> {\n    const tag = buffer[0];\n    const data = buffer.subarray(1);\n    switch (tag) {\n      case 0:\n        return data;\n      case 1:\n        // Some runtimes support brotli, but it's not yet defined in `lib.dom.d.ts`.\n        // We assert runtime support in `DbConnectionBuilder.withCompression`, so\n        // this cast is safe.\n        return await decompress(data, 'brotli' as CompressionFormat);\n      case 2:\n        return await decompress(data, 'gzip');\n      default:\n        throw new Error(\n          'Unexpected Compression Algorithm. Please use `gzip` or `none`'\n        );\n    }\n  }\n\n  send(msg: Uint8Array<ArrayBuffer>): void {\n    this.#ws.send(msg);\n  }\n\n  close(): void {\n    this.#ws.close();\n  }\n\n  constructor(ws: WebSocket) {\n    this.#ws = ws;\n  }\n\n  static async openWebSocket(","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-typescript/src/sdk/websocket_decompress_adapter.ts#L41-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Align versions: upgrade the TypeScript SDK to match the spacetimedb server version (or downgrade the server) so both agree on the compression tags","As a workaround, build the connection with .withCompression('none') so the server sends tag 0 and payloads pass through untouched","Remove or bypass any proxy/middleware between client and server that could rewrite binary WebSocket frames","If you inject a custom WebSocketFactory, verify it hands the SDK the raw, unmodified frame bytes"],"exampleFix":"// before\nconst db = DbConnection.builder()\n  .withUri('ws://localhost:3000')\n  .withModuleName('my_module')\n  .build(); // server uses a compression tag this SDK doesn't know\n\n// after: pin compression to 'none' until SDK and server versions match\nconst db = DbConnection.builder()\n  .withUri('ws://localhost:3000')\n  .withModuleName('my_module')\n  .withCompression('none')\n  .build();","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"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.","preventionTips":["Pin the TypeScript SDK and spacetimedb server versions together and upgrade them in lockstep","Prefer 'none' or 'gzip' compression in environments with proxies or unusual runtimes","Never place middleware that rewrites binary WebSocket frames between client and server","Exercise the chosen compression setting in CI against the exact server version you deploy"],"tags":["websocket","compression","protocol-mismatch","typescript"],"backgroundTag":"protocol-version-mismatch","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}