clockworklabs/SpacetimeDB · error · TypeError

Option 'ignoreBOM' not supported

Error message

Option 'ignoreBOM' not supported

What it means

The built-in TextDecoder polyfill in the SpacetimeDB V8 host supports only the fatal option. If options.ignoreBOM is truthy, the constructor throws TypeError('Option ignoreBOM not supported'), and the ignoreBOM getter is hardwired to return false (BOM kept as U+FEFF, the encoding-spec default).

Source

Thrown at crates/core/src/host/v8/builtins/text_encoding.js:37

globalThis.TextDecoder = class TextDecoder {
  /** @type {string} */
  #encoding;

  /** @type {boolean} */
  #fatal;

  /**
   * @argument {string} label
   * @argument {any} options
   */
  constructor(label = 'utf-8', options = {}) {
    if (label !== 'utf-8') {
      throw new RangeError('The encoding label provided is invalid');
    }
    this.#encoding = label;
    this.#fatal = !!options.fatal;
    if (options.ignoreBOM) {
      throw new TypeError("Option 'ignoreBOM' not supported");
    }
  }

  get encoding() {
    return this.#encoding;
  }
  get fatal() {
    return this.#fatal;
  }
  get ignoreBOM() {
    return false;
  }

  /**
   * @argument {any} input
   * @argument {any} options
   */
  decode(input, options = {}) {

View on GitHub (pinned to 524b4487d9)

Solutions

1. Omit the ignoreBOM option entirely — it is not configurable in this polyfill
2. Strip the BOM bytes yourself before decoding: check for 0xEF 0xBB 0xBF and subarray(3)
3. Do BOM-sensitive decoding outside the module and send clean UTF-8 in

Example fix

// before
const text = new TextDecoder('utf-8', { ignoreBOM: true }).decode(bytes);

// after
const noBom = bytes[0] === 0xEF && bytes[1] === 0xBB && bytes[2] === 0xBF ? bytes.subarray(3) : bytes;
const text = new TextDecoder('utf-8').decode(noBom);

// Only pass options the polyfill supports:
const dec = new TextDecoder('utf-8', { fatal: opts.fatal }); // ignoreBOM intentionally dropped

function isSupportedDecoderOptions(o: { fatal?: boolean; ignoreBOM?: boolean }): boolean {
  return !o.ignoreBOM; // truthy ignoreBOM is the only rejected option
}

try {
  dec = new TextDecoder('utf-8', options);
} catch (e) {
  if (e instanceof TypeError && /ignoreBOM/.test(e.message)) {
    const { ignoreBOM: _drop, ...rest } = options;
    dec = new TextDecoder('utf-8', rest);
  } else throw e;
}

When it happens

Trigger: Calling new TextDecoder('utf-8', { ignoreBOM: true }) with any truthy value; note that { ignoreBOM: false } is accepted since only truthy values hit the check.

Common situations: Copying browser code that strips a byte-order mark via ignoreBOM; decoding files that carry BOMs (Windows-authored JSON/CSV) inside a module.

Related errors

• The encoding label provided is invalid
• Option 'stream' not supported
• Math.random is not available in SpacetimeDB modules. Use ctx
• must export schema as default export
• default export is not a Schema object

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