What causes "Cannot use more than one PDFWorker per port." in mozilla/pdf.js?

Use PDFWorker.create({ port }) instead of new PDFWorker({ port }); it returns the cached instance.

mozilla/pdf.js · error · Error

Cannot use more than one PDFWorker per port.

Error message

Cannot use more than one PDFWorker per port.

What it means

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.

Source

Thrown at src/display/api.js:2140

      this._resetGlobalState = () => {
        this.#isWorkerDisabled = false;
        delete globalThis.pdfjsWorker;
      };
    }
  }

  constructor({
    name = null,
    port = null,
    verbosity = getVerbosityLevel(),
  } = {}) {
    this.name = name;
    this.destroyed = false;
    this.verbosity = verbosity;

    if (port) {
      if (PDFWorker.#workerPorts.has(port)) {
        throw new Error("Cannot use more than one PDFWorker per port.");
      }
      PDFWorker.#workerPorts.set(port, this);
      this.#initializeFromPort(port);
    } else {
      this.#initialize();
    }

    if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
      // For testing purposes.
      Object.defineProperty(this, "_webWorker", {
        get() {
          return this.#webWorker;
        },
      });
    }
  }

  /**

View on GitHub (pinned to 5903d58d58)

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.

Example fix

// before
const w1 = new pdfjsLib.PDFWorker({ port });
const w2 = new pdfjsLib.PDFWorker({ port }); // throws

// after
const w1 = pdfjsLib.PDFWorker.create({ port });
const w2 = pdfjsLib.PDFWorker.create({ port }); // returns same w1

Defensive patterns

Strategy: validation

Validate before calling

// Prefer the factory; it returns the cached instance instead of throwing.
const worker = pdfjsLib.PDFWorker.create({ port });
// never: new pdfjsLib.PDFWorker({ port })

Prevention

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.

When it happens

Trigger: 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.

Common situations: Multi-viewer pages sharing a worker pool; refactors that moved worker creation into a loop; testing harnesses that re-instantiate viewers without cleanup.

Related errors

AI-assisted analysis of mozilla/pdf.js@5903d58d58 (2026-08-13). Data as JSON: /api/errors/7a6a3638e7a9359a. Report an issue: GitHub.