{"record":{"id":"d9d313cd0ddf2c49","repo":"mozilla/pdf.js","slug":"openjpeg-failed-to-initialize","errorCode":null,"errorMessage":"OpenJPEG failed to initialize","messagePattern":"OpenJPEG failed to initialize","errorType":"exception","errorClass":"JpxError","httpStatus":null,"severity":"error","filePath":"src/core/jpx.js","lineNumber":48,"sourceCode":"  _noWasmFilename = \"openjpeg_nowasm_fallback.js\";\n\n  static get instance() {\n    return shadow(this, \"instance\", new JpxImage(/* trackInstance = */ true));\n  }\n\n  async decode(\n    bytes,\n    {\n      numComponents = 4,\n      isIndexedColormap = false,\n      smaskInData = false,\n      reducePower = 0,\n    } = {}\n  ) {\n    const module = await this._getModule(OpenJPEG);\n\n    if (!module) {\n      throw new JpxError(\"OpenJPEG failed to initialize\");\n    }\n    let ptr;\n\n    try {\n      const size = bytes.length;\n      ptr = module._malloc(size);\n      module.writeArrayToMemory(bytes, ptr);\n      const ret = module._jp2_decode(\n        ptr,\n        size,\n        numComponents > 0 ? numComponents : 0,\n        !!isIndexedColormap,\n        !!smaskInData,\n        reducePower\n      );\n      if (ret) {\n        const { errorMessages } = module;\n        if (errorMessages) {","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/src/core/jpx.js#L30-L66","documentation":"Thrown by JpxImage.decode() when _getModule(OpenJPEG) returns a falsy module. _getModule lazily loads and instantiates the OpenJPEG WASM; a null/undefined result means the WASM module never initialized. This is an environment/setup failure, not an image-data problem.","triggerScenarios":"Awaiting this._getModule(OpenJPEG) yields a falsy value. Happens when openjpeg.wasm cannot be fetched (404/network), WebAssembly isn't supported/enabled, a CSP blocks 'wasm-unsafe-eval' or worker src, or the WASM file is missing from the deployment.","commonSituations":"Self-hosted PDF.js where the build/ assets (openjpeg.wasm / openjpeg_nowasm_fallback.js) weren't copied alongside the JS bundle. A strict Content-Security-Policy without wasm-src. Older browsers or non-WASM Node environments. Misconfigured workerBasePath/baseUrl.","solutions":["Verify openjpeg.wasm (and the asm.js fallback) exist in the deployed assets directory next to pdf.worker.js.","Add 'wasm-unsafe-eval' (or 'script-src' allowing the worker) to your Content-Security-Policy header.","Confirm the browser supports WebAssembly (typeof WebAssembly !== 'undefined').","Check network tab for 404s on the .wasm URL; fix the base path / CDN configuration."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"async function ensureWasm() {\n  if (typeof WebAssembly === 'undefined') throw new Error('WebAssembly not available');\n  // confirm the wasm asset is reachable\n  const res = await fetch(wasmUrl, { method: 'HEAD' });\n  if (!res.ok) throw new Error('openjpeg.wasm not reachable: ' + res.status);\n}","typeGuard":"function wasmSupported() {\n  return typeof WebAssembly === 'object' && typeof WebAssembly.instantiate === 'function';\n}","tryCatchPattern":"try { imageData = await JpxImage.instance.decode(bytes); }\ncatch (e) { if (e.name === 'JpxError' && /initialize/.test(e.message)) { /* env/setup issue */ } else throw e; }","preventionTips":["Ship openjpeg.wasm and the asm.js fallback alongside pdf.worker.js in your deployment.","Allow 'wasm-unsafe-eval' in your Content-Security-Policy.","Detect WebAssembly support up front and fail with a clear message.","Verify no 404s on the .wasm URL via the network tab."],"tags":["jpeg2000","wasm","environment","initialization","jpx"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}