evanw/esbuild · critical · Error

Invariant violation: "${encodeInvariant} instanceof Uint8Arr

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

After picking a UTF-8 codec, lib/shared/stdio_protocol.ts:439 verifies the invariant that encodeUTF8('') returns a Uint8Array instance. The check exists specifically because Jest (and some other test runners / instrumented runtimes) monkeypatch Uint8Array/Buffer such that Buffer.from('') or TextEncoder().encode('') is no longer detected as instanceof Uint8Array. When the invariant fails, esbuild refuses to start because internal byte marshalling would silently corrupt data. The message is explicit that this is an environment bug, not esbuild's fault.

Source

Thrown at lib/shared/stdio_protocol.ts:440

// 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 6ff1d8b0d8)

Solutions

1. In Jest, set testEnvironment to 'node' (or upgrade jest-environment-jsdom to a version that doesn't break Buffer).
2. Remove or upgrade conflicting buffer/uint8array polyfills so Buffer extends Uint8Array.
3. Update @types/node and the test runner to versions where the prototype chain is intact.

Example fix

// before — jest.config.js
module.exports = { testEnvironment: 'jsdom' };
// after
module.exports = { testEnvironment: 'node' };

function assertUint8ArrayInvariant() {
  const enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
  const sample = enc ? enc.encode('') : Buffer.from('');
  if (!(sample instanceof Uint8Array)) {
    throw new Error('Environment bug: TextEncoder/Buffer does not produce a Uint8Array. Fix Jest env / buffer polyfill.');
  }
}

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

When it happens

Trigger: Running esbuild under Jest with an outdated jsdom environment that patches Buffer. Using a runtime that returns a non-Uint8Array-typed object from TextEncoder.prototype.encode (some polyfills). Conflicting versions of node types / buffer polyfills in a monorepo.

Common situations: Jest tests that import code which transitively loads esbuild, in a testEnvironment set to 'jsdom' with stale buffer polyfills. Webpack 4 bundling that ships a buffer polyfill not extending Uint8Array. Mixed @types/node versions where Buffer instanceof checks break.

Related errors

• No UTF-8 codec found
• Module not found in bundle: ${path}
• The "write" option is unavailable in this environment
• Cannot use the "watch" API in this environment
• Cannot use the "serve" API in this environment

AI-assisted analysis of evanw/esbuild@6ff1d8b0d8 (2026-08-03). Data as JSON: /data/errors/0087e683aaf72dd1.json. Report an issue: GitHub.