{"record":{"id":"7a6a3638e7a9359a","repo":"mozilla/pdf.js","slug":"cannot-use-more-than-one-pdfworker-per-port","errorCode":null,"errorMessage":"Cannot use more than one PDFWorker per port.","messagePattern":"Cannot use more than one PDFWorker per port\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/display/api.js","lineNumber":2140,"sourceCode":"      this._resetGlobalState = () => {\n        this.#isWorkerDisabled = false;\n        delete globalThis.pdfjsWorker;\n      };\n    }\n  }\n\n  constructor({\n    name = null,\n    port = null,\n    verbosity = getVerbosityLevel(),\n  } = {}) {\n    this.name = name;\n    this.destroyed = false;\n    this.verbosity = verbosity;\n\n    if (port) {\n      if (PDFWorker.#workerPorts.has(port)) {\n        throw new Error(\"Cannot use more than one PDFWorker per port.\");\n      }\n      PDFWorker.#workerPorts.set(port, this);\n      this.#initializeFromPort(port);\n    } else {\n      this.#initialize();\n    }\n\n    if (typeof PDFJSDev === \"undefined\" || PDFJSDev.test(\"TESTING\")) {\n      // For testing purposes.\n      Object.defineProperty(this, \"_webWorker\", {\n        get() {\n          return this.#webWorker;\n        },\n      });\n    }\n  }\n\n  /**","sourceCodeStart":2122,"sourceCodeEnd":2158,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/src/display/api.js#L2122-L2158","documentation":"A generic Error from the PDFWorker constructor: when a port is supplied and that exact port is already registered in the static PDFWorker.#workerPorts map, construction is refused. pdf.js enforces a 1:1 mapping between a MessagePort/Worker and a PDFWorker to prevent two wrappers from driving one port. To reuse a port, call PDFWorker.create({port}) which returns the existing instance.","triggerScenarios":"Calling new PDFWorker({ port }) twice with the same Worker/MessagePort; mixing manual PDFWorker construction with getDocument({worker}) reuse; sharing a worker port across two viewer instances via constructor.","commonSituations":"Multi-viewer pages sharing a worker pool; refactors that moved worker creation into a loop; testing harnesses that re-instantiate viewers without cleanup.","solutions":["Use PDFWorker.create({ port }) instead of new PDFWorker({ port }); it returns the cached instance.","Call worker.destroy() (and await it) before constructing a new PDFWorker on the same port.","Let getDocument manage its own worker when reuse is not required."],"exampleFix":"// before\nconst w1 = new pdfjsLib.PDFWorker({ port });\nconst w2 = new pdfjsLib.PDFWorker({ port }); // throws\n\n// after\nconst w1 = pdfjsLib.PDFWorker.create({ port });\nconst w2 = pdfjsLib.PDFWorker.create({ port }); // returns same w1","handlingStrategy":"validation","validationCode":"// Prefer the factory; it returns the cached instance instead of throwing.\nconst worker = pdfjsLib.PDFWorker.create({ port });\n// never: new pdfjsLib.PDFWorker({ port })","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always use PDFWorker.create({port}) rather than new PDFWorker({port}).","Await worker.destroy() before constructing a new PDFWorker on the same port.","Let getDocument manage its own worker when reuse is unnecessary."],"tags":["worker","api-usage","lifecycle","port","validation"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}