evanw/esbuild · critical · Error

Invariant violation: " instanceof Uint8Array" is…

Error message

Invariant violation: "${encodeInvariant} instanceof Uint8Array" is incorrectly false

This indicates that your JavaScript environment is broken. You cannot use
esbuild in this environment because esbuild relies on this invariant. This
is not a problem with esbuild. You need to fix your environment instead.

What it means

At module load (lib/shared/stdio_protocol.ts:440), esbuild verifies a foundational invariant: that its UTF-8 encoder returns a `Uint8Array` for the empty string. The encoder is chosen from `TextEncoder` (invariant label `new TextEncoder().encode("")`) or Node's `Buffer.from` (label `Buffer.from("")`). If the result is not an instance of `Uint8Array`, the runtime itself is broken (most famously certain Jest versions that patch globals/prototype chains), and esbuild refuses to run rather than emit confusing downstream errors.

Solutions

1. Update or fix your test environment (Jest/jsdom) so `new TextEncoder().encode('') instanceof Uint8Array` is true.
2. Avoid test setup files that replace global `Uint8Array`, `TextEncoder`, or `Buffer`.
3. Run esbuild in a child process or worker that is not affected by the test framework's global patches.

Example fix

// before — Jest config with a custom environment that breaks Uint8Array
testEnvironment: 'jsdom-with-patches'
// after — use a standard environment or node
testEnvironment: 'node'

// Early environment sanity check before using esbuild
function assertUtf8Invariant(): void {
  const enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
  const out = enc ? enc.encode('') : (typeof Buffer !== 'undefined' ? Buffer.from('') : null);
  if (!(out instanceof Uint8Array)) throw new Error('Runtime breaks Uint8Array invariant; fix your JS environment (e.g. Jest).');
}
assertUtf8Invariant();

function environmentSupportsEsbuild(): boolean {
  try {
    const enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
    const out = enc ? enc.encode('') : (typeof Buffer !== 'undefined' ? Buffer.from('') : null);
    return out instanceof Uint8Array;
  } catch { return false; }
}

When it happens

Trigger: Importing esbuild inside a test environment (Jest) that monkeypatches `Uint8Array`, `TextEncoder`, or `Buffer` prototypes so that `instanceof Uint8Array` returns false even for valid buffers.

Common situations: Running esbuild under an old/broken Jest configuration; a custom environment that overrides global `Uint8Array`; a polyfill/shim that redefines typed-array constructors; an outdated jsdom environment.

Related errors

• Cannot use the "serve" API in this environment
• Cannot use the "watch" API in this environment
• Module not found in bundle
• The "worker" option only works in the browser
• The "write" option is unavailable in this environment

AI-assisted analysis of evanw/esbuild@f6058f8364 (2026-08-09). Data as JSON: /api/errors/0087e683aaf72dd1. Report an issue: GitHub.

Appendix: source

Thrown at lib/shared/stdio_protocol.ts:441

// For node 10.x
else if (typeof Buffer !== 'undefined') {
  encodeUTF8 = text => Buffer.from(text)
  decodeUTF8 = bytes => {
    let { buffer, byteOffset, byteLength } = bytes
    return Buffer.from(buffer, byteOffset, byteLength).toString()
  }
  encodeInvariant = 'Buffer.from("")'
}

else {
  throw new Error('No UTF-8 codec found')
}

// Throw an error early if this isn't true. The test framework called "Jest"
// has some bugs regarding this edge case, and letting esbuild proceed further
// leads to confusing errors that make it seem like esbuild itself has a bug.
if (!(encodeUTF8('') instanceof Uint8Array))
  throw new Error(`Invariant violation: "${encodeInvariant} instanceof Uint8Array" is incorrectly false

This indicates that your JavaScript environment is broken. You cannot use
esbuild in this environment because esbuild relies on this invariant. This
is not a problem with esbuild. You need to fix your environment instead.
`)

export function readUInt32LE(buffer: Uint8Array, offset: number): number {
  return (
    buffer[offset++] |
    (buffer[offset++] << 8) |
    (buffer[offset++] << 16) |
    (buffer[offset++] << 24)
  ) >>> 0
}

function writeUInt32LE(buffer: Uint8Array, value: number, offset: number): void {
  buffer[offset++] = value
  buffer[offset++] = value >> 8

View on GitHub (pinned to f6058f8364)