{"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":440,"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":422,"sourceCodeEnd":458,"githubUrl":"https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/shared/stdio_protocol.ts#L422-L458","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["In Jest, set testEnvironment to 'node' (or upgrade jest-environment-jsdom to a version that doesn't break Buffer).","Remove or upgrade conflicting buffer/uint8array polyfills so Buffer extends Uint8Array.","Update @types/node and the test runner to versions where the prototype chain is intact."],"exampleFix":"// before — jest.config.js\nmodule.exports = { testEnvironment: 'jsdom' };\n// after\nmodule.exports = { testEnvironment: 'node' };","handlingStrategy":"validation","validationCode":"function assertUint8ArrayInvariant() {\n  const enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;\n  const sample = enc ? enc.encode('') : Buffer.from('');\n  if (!(sample instanceof Uint8Array)) {\n    throw new Error('Environment bug: TextEncoder/Buffer does not produce a Uint8Array. Fix Jest env / buffer polyfill.');\n  }\n}","typeGuard":"function encodeProducesUint8Array(): boolean {\n  try {\n    const e = typeof TextEncoder !== 'undefined' ? new TextEncoder().encode('') : Buffer.from('');\n    return e instanceof Uint8Array;\n  } catch { return false; }\n}","tryCatchPattern":null,"preventionTips":["In Jest, prefer testEnvironment: 'node'; upgrade jest-environment-jsdom if you must use jsdom.","Avoid bundling buffer polyfills that don't extend Uint8Array (e.g. old 'buffer' package versions).","Keep @types/node and your test runner versions aligned."],"tags":["environment","uint8array","jest","runtime","initialization"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}