golang/go · critical · Error

globalThis.TextDecoder is not available, polyfill required

Error message

globalThis.TextDecoder is not available, polyfill required

What it means

Thrown by wasm_exec.js when globalThis.TextDecoder is missing at load time. TextDecoder turns UTF-8 bytes read from Go wasm memory back into JS strings. Like the other polyfill gates, it fires during module initialization, before go.run() can be invoked.

Source

Thrown at lib/wasm/wasm_exec.js:97

				return pathSegments.join("/");
			}
		}
	}

	if (!globalThis.crypto) {
		throw new Error("globalThis.crypto is not available, polyfill required (crypto.getRandomValues only)");
	}

	if (!globalThis.performance) {
		throw new Error("globalThis.performance is not available, polyfill required (performance.now only)");
	}

	if (!globalThis.TextEncoder) {
		throw new Error("globalThis.TextEncoder is not available, polyfill required");
	}

	if (!globalThis.TextDecoder) {
		throw new Error("globalThis.TextDecoder is not available, polyfill required");
	}

	const encoder = new TextEncoder("utf-8");
	const decoder = new TextDecoder("utf-8");

	globalThis.Go = class {
		constructor() {
			this.argv = ["js"];
			this.env = {};
			this.exit = (code) => {
				if (code !== 0) {
					console.warn("exit code:", code);
				}
			};
			this._exitPromise = new Promise((resolve) => {
				this._resolveExitPromise = resolve;
			});
			this._pendingEvent = null;

View on GitHub (pinned to b6b368adc5)

Solutions

Use Node.js >= 11 where TextDecoder is a global.
Polyfill: globalThis.TextDecoder = require('node:util').TextDecoder; before requiring wasm_exec.js.
Use the text-encoding polyfill package: globalThis.TextDecoder = require('text-encoding').TextDecoder;.
Propagate TextDecoder into any vm.createContext sandbox explicitly.

Example fix

// before
require('./wasm_exec.js'); // throws: globalThis.TextDecoder is not available

// after
const { TextDecoder } = require('node:util');
globalThis.TextDecoder = TextDecoder;
require('./wasm_exec.js');

Defensive patterns

Strategy: validation

Validate before calling

if (typeof globalThis.TextDecoder === 'undefined') {
  globalThis.TextDecoder = require('node:util').TextDecoder;
}

Type guard

const hasTextDecoder = () => typeof globalThis.TextDecoder === 'function';

Prevention

Use Node >= 11 (TextDecoder is global).
Add TextDecoder to your bootstrap polyfill module.
Inject TextDecoder into vm.createContext sandboxes explicitly.

When it happens

Trigger: Loading wasm_exec.js in a runtime lacking the Encoding Living Standard TextDecoder: old Node (< 11), minimal embedded engines, vm contexts without inherited globals.

Common situations: Calling Go wasm from legacy Node; running in a locked-down VM sandbox; using a JS engine whose text-encoding module is opt-in.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/4d92e2c2b2baa9cd. Report an issue: GitHub.