{"record":{"id":"0087e683aaf72dd1","repo":"evanw/esbuild","slug":"invariant-violation-encodeinvariant-instanceo","errorCode":null,"errorMessage":"Invariant violation: \"${encodeInvariant} instanceof Uint8Array\" is incorrectly false\n\nThis indicates that your JavaScript environment is broken. You cannot use\nesbuild in this environment because esbuild relies on this invariant. This\nis not a problem with esbuild. You need to fix your environment instead.\n","messagePattern":"Invariant violation: \"(.+?) instanceof Uint8Array\" is incorrectly false\n\nThis indicates that your JavaScript environment is broken\\. You cannot use\nesbuild in this environment because esbuild relies on this invariant\\. This\nis not a problem with esbuild\\. You need to fix your environment instead\\.\n","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"lib/shared/stdio_protocol.ts","lineNumber":441,"sourceCode":"// For node 10.x\nelse if (typeof Buffer !== 'undefined') {\n  encodeUTF8 = text => Buffer.from(text)\n  decodeUTF8 = bytes => {\n    let { buffer, byteOffset, byteLength } = bytes\n    return Buffer.from(buffer, byteOffset, byteLength).toString()\n  }\n  encodeInvariant = 'Buffer.from(\"\")'\n}\n\nelse {\n  throw new Error('No UTF-8 codec found')\n}\n\n// Throw an error early if this isn't true. The test framework called \"Jest\"\n// has some bugs regarding this edge case, and letting esbuild proceed further\n// leads to confusing errors that make it seem like esbuild itself has a bug.\nif (!(encodeUTF8('') instanceof Uint8Array))\n  throw new Error(`Invariant violation: \"${encodeInvariant} instanceof Uint8Array\" is incorrectly false\n\nThis indicates that your JavaScript environment is broken. You cannot use\nesbuild in this environment because esbuild relies on this invariant. This\nis not a problem with esbuild. You need to fix your environment instead.\n`)\n\nexport function readUInt32LE(buffer: Uint8Array, offset: number): number {\n  return (\n    buffer[offset++] |\n    (buffer[offset++] << 8) |\n    (buffer[offset++] << 16) |\n    (buffer[offset++] << 24)\n  ) >>> 0\n}\n\nfunction writeUInt32LE(buffer: Uint8Array, value: number, offset: number): void {\n  buffer[offset++] = value\n  buffer[offset++] = value >> 8","sourceCodeStart":423,"sourceCodeEnd":459,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/shared/stdio_protocol.ts#L423-L459","documentation":"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.","triggerScenarios":"Importing esbuild inside a test environment (Jest) that monkeypatches `Uint8Array`, `TextEncoder`, or `Buffer` prototypes so that `instanceof Uint8Array` returns false even for valid buffers.","commonSituations":"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.","solutions":["Update or fix your test environment (Jest/jsdom) so `new TextEncoder().encode('') instanceof Uint8Array` is true.","Avoid test setup files that replace global `Uint8Array`, `TextEncoder`, or `Buffer`.","Run esbuild in a child process or worker that is not affected by the test framework's global patches."],"exampleFix":"// before — Jest config with a custom environment that breaks Uint8Array\ntestEnvironment: 'jsdom-with-patches'\n// after — use a standard environment or node\ntestEnvironment: 'node'","handlingStrategy":"validation","validationCode":"// Early environment sanity check before using esbuild\nfunction assertUtf8Invariant(): void {\n  const enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;\n  const out = enc ? enc.encode('') : (typeof Buffer !== 'undefined' ? Buffer.from('') : null);\n  if (!(out instanceof Uint8Array)) throw new Error('Runtime breaks Uint8Array invariant; fix your JS environment (e.g. Jest).');\n}\nassertUtf8Invariant();","typeGuard":"function environmentSupportsEsbuild(): boolean {\n  try {\n    const enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;\n    const out = enc ? enc.encode('') : (typeof Buffer !== 'undefined' ? Buffer.from('') : null);\n    return out instanceof Uint8Array;\n  } catch { return false; }\n}","tryCatchPattern":null,"preventionTips":["Avoid test setup files that patch global Uint8Array/Buffer/TextEncoder.","Keep Jest/jsdom versions current; run esbuild in a plain node worker if needed."],"tags":["environment","jest","runtime","invariant","utf8"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}