clockworklabs/SpacetimeDB · error · TypeError

Brotli compression is not supported by the runtime. Please c

Error message

Brotli compression is not supported by the runtime. Please choose a different compression method.

What it means

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.

Source

Thrown at crates/bindings-typescript/src/sdk/db_connection_builder.ts:101

    return this;
  }

  withWSFn(createWSFn: WebSocketFactory): this {
    this.#createWSFn = createWSFn;
    return this;
  }

  /**
   * Set the compression algorithm to use for the connection.
   *
   * @param compression The compression algorithm to use for the connection.
   */
  withCompression(compression: 'gzip' | 'brotli' | 'none'): this {
    if (compression === 'brotli') {
      try {
        new DecompressionStream('brotli' as CompressionFormat);
      } catch (e) {
        throw new TypeError(
          `Brotli compression is not supported by the runtime. Please choose a different compression method.`,
          { cause: e }
        );
      }
    }
    this.#compression = compression;
    return this;
  }

  /**
   * Sets the connection to operate in light mode.
   *
   * Light mode is a mode that reduces the amount of data sent over the network.
   *
   * @param lightMode The light mode for the connection.
   */
  withLightMode(lightMode: boolean): this {
    this.#lightMode = lightMode;

View on GitHub (pinned to 524b4487d9)

Solutions

1. Choose 'gzip' or 'none' instead of 'brotli'
2. Feature-detect brotli support before selecting it (try/catch around new DecompressionStream('brotli'))
3. Upgrade the runtime (Node >= 21.2 or a current browser) if brotli is required

Example fix

// before
DbConnection.builder().withCompression('brotli'); // throws on old runtimes

// after
const brotli = (() => { try { new DecompressionStream('brotli'); return true; } catch { return false; } })();
DbConnection.builder().withCompression(brotli ? 'brotli' : 'gzip');

function runtimeSupportsBrotli(): boolean {
  try {
    new DecompressionStream('brotli');
    return true;
  } catch {
    return false;
  }
}
DbConnection.builder().withCompression(runtimeSupportsBrotli() ? 'brotli' : 'gzip');

try {
  builder.withCompression('brotli');
} catch (e) {
  if (e instanceof TypeError && e.message.includes('Brotli')) {
    builder.withCompression('gzip');
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unexpected Compression Algorithm. Please use `gzip` or `none
• 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/a024249b3470dc87. Report an issue: GitHub.