{"record":{"id":"a024249b3470dc87","repo":"clockworklabs/SpacetimeDB","slug":"brotli-compression-is-not-supported-by-the-runtime","errorCode":null,"errorMessage":"Brotli compression is not supported by the runtime. Please choose a different compression method.","messagePattern":"Brotli compression is not supported by the runtime\\. Please choose a different compression method\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/sdk/db_connection_builder.ts","lineNumber":101,"sourceCode":"    return this;\n  }\n\n  withWSFn(createWSFn: WebSocketFactory): this {\n    this.#createWSFn = createWSFn;\n    return this;\n  }\n\n  /**\n   * Set the compression algorithm to use for the connection.\n   *\n   * @param compression The compression algorithm to use for the connection.\n   */\n  withCompression(compression: 'gzip' | 'brotli' | 'none'): this {\n    if (compression === 'brotli') {\n      try {\n        new DecompressionStream('brotli' as CompressionFormat);\n      } catch (e) {\n        throw new TypeError(\n          `Brotli compression is not supported by the runtime. Please choose a different compression method.`,\n          { cause: e }\n        );\n      }\n    }\n    this.#compression = compression;\n    return this;\n  }\n\n  /**\n   * Sets the connection to operate in light mode.\n   *\n   * Light mode is a mode that reduces the amount of data sent over the network.\n   *\n   * @param lightMode The light mode for the connection.\n   */\n  withLightMode(lightMode: boolean): this {\n    this.#lightMode = lightMode;","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-typescript/src/sdk/db_connection_builder.ts#L83-L119","documentation":"DbConnection.builder().withCompression('brotli') probes the runtime by constructing new DecompressionStream('brotli'). The WebSocket message decompression relies on the Web Compression Streams API, and not every runtime accepts the 'brotli' format. When the constructor throws, the builder wraps it in a TypeError with the original error attached as cause.","triggerScenarios":"Calling withCompression('brotli') in a runtime whose DecompressionStream lacks brotli support: older Node.js releases (brotli in Web Compression Streams arrived in Node 21.2), older Safari/Firefox builds, or an environment where DecompressionStream is polyfilled for gzip/deflate only.","commonSituations":"CI pipelines on an older Node image than local dev; shipping to browsers a generation behind; a bundler polyfill (e.g. for Node <17) that only implements gzip/deflate.","solutions":["Choose 'gzip' or 'none' instead of 'brotli'","Feature-detect brotli support before selecting it (try/catch around new DecompressionStream('brotli'))","Upgrade the runtime (Node >= 21.2 or a current browser) if brotli is required"],"exampleFix":"// before\nDbConnection.builder().withCompression('brotli'); // throws on old runtimes\n\n// after\nconst brotli = (() => { try { new DecompressionStream('brotli'); return true; } catch { return false; } })();\nDbConnection.builder().withCompression(brotli ? 'brotli' : 'gzip');","handlingStrategy":"validation","validationCode":"function runtimeSupportsBrotli(): boolean {\n  try {\n    new DecompressionStream('brotli');\n    return true;\n  } catch {\n    return false;\n  }\n}\nDbConnection.builder().withCompression(runtimeSupportsBrotli() ? 'brotli' : 'gzip');","typeGuard":null,"tryCatchPattern":"try {\n  builder.withCompression('brotli');\n} catch (e) {\n  if (e instanceof TypeError && e.message.includes('Brotli')) {\n    builder.withCompression('gzip');\n  } else throw e;\n}","preventionTips":["Feature-detect compression support instead of hardcoding 'brotli'","Run CI on the same Node version as production to catch DecompressionStream gaps","Prefer 'gzip' for portable clients; it is supported everywhere the SDK runs"],"tags":["compression","brotli","runtime-support","websocket","typescript"],"backgroundTag":"unsupported-compression-format","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}