{"id":"83a8208a21485538","repo":"evanw/esbuild","slug":"no-utf-8-codec-found","errorCode":null,"errorMessage":"No UTF-8 codec found","messagePattern":"No UTF-8 codec found","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"lib/shared/stdio_protocol.ts","lineNumber":433,"sourceCode":"  let encoder = new TextEncoder()\n  let decoder = new TextDecoder()\n  encodeUTF8 = text => encoder.encode(text)\n  decodeUTF8 = bytes => decoder.decode(bytes)\n  encodeInvariant = 'new TextEncoder().encode(\"\")'\n}\n\n// 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) |","sourceCodeStart":415,"sourceCodeEnd":451,"githubUrl":"https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/shared/stdio_protocol.ts#L415-L451","documentation":"esbuild's stdio protocol layer needs to encode/decode UTF-8 between JS and the Go binary. lib/shared/stdio_protocol.ts:414-433 probes for TextEncoder/TextDecoder first (modern browsers and Node ≥12), then falls back to Buffer (Node 10), and if neither global is present, throws 'No UTF-8 codec found'. This is an environment-capability guard: the host JS runtime lacks both the Web TextCodec API and Node's Buffer, so esbuild cannot marshal strings.","triggerScenarios":"Running esbuild in a stripped-down JS engine that defines neither TextEncoder nor Buffer (some embedded JS runtimes, ancient browsers, or a polyfill-less environment). A bundler that tree-shook away a TextEncoder polyfill. Node started with --no-experimental-strip-types and a custom global setup that deleted Buffer.","commonSituations":"Edge/embedded JS engines (QuickJS, Hermes without textcodec polyfill). Older Internet Explorer without TextEncoder and without a Buffer shim. Test environments that sandbox globals.","solutions":["Provide a TextEncoder/TextDecoder polyfill (e.g. 'fast-text-encoding', 'text-encoding') before importing esbuild.","Run in a modern Node (≥12) or any current browser where TextEncoder is global.","If you control the runtime, ensure the global TextEncoder constructor is defined on globalThis."],"exampleFix":"// before — esbuild imported in an engine without TextEncoder\nimport * as esbuild from 'esbuild';\n// throws: No UTF-8 codec found\n\n// after — polyfill first\nimport 'fast-text-encoding';\nimport * as esbuild from 'esbuild';","handlingStrategy":"validation","validationCode":"function ensureUtf8Codec() {\n  if (typeof TextEncoder === 'undefined' && typeof Buffer === 'undefined') {\n    throw new Error('This environment has no UTF-8 codec; import a TextEncoder polyfill before esbuild.');\n  }\n}\nensureUtf8Codec();\nimport 'esbuild';","typeGuard":"function hasUtf8Codec(): boolean {\n  return typeof TextEncoder !== 'undefined' && typeof TextDecoder !== 'undefined'\n    || typeof Buffer !== 'undefined';\n}","tryCatchPattern":null,"preventionTips":["In embedded/legacy engines, import 'fast-text-encoding' before esbuild.","Run esbuild under Node ≥12 or any modern browser.","If you control the runtime, expose globalThis.TextEncoder."],"tags":["environment","utf8","runtime","initialization"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}