mozilla/pdf.js · error · Error

Invalid `workerPort` type.

Error message

Invalid `workerPort` type.

What it means

Thrown by the GlobalWorkerOptions.workerPort setter when the value is not null and not an instance of Worker. The setter accepts only a real Web Worker (or null to clear it) because the port is used directly for message passing. Any other value (a MessagePort, a function, an object) is rejected.

Source

Thrown at src/display/worker_options.js:37

  static #src = "";

  /**
   * @type {Worker | null}
   */
  static get workerPort() {
    return this.#port;
  }

  /**
   * @param {Worker | null} workerPort - Defines global port for worker process.
   *   Overrides the `workerSrc` option.
   */
  static set workerPort(val) {
    if (
      !(typeof Worker !== "undefined" && val instanceof Worker) &&
      val !== null
    ) {
      throw new Error("Invalid `workerPort` type.");
    }
    this.#port = val;
  }

  /**
   * @type {string}
   */
  static get workerSrc() {
    return this.#src;
  }

  /**
   * @param {string} workerSrc - A string containing the path and filename of
   *   the worker file.
   *
   *   NOTE: The `workerSrc` option should always be set, in order to prevent
   *         any issues when using the PDF.js library.
   */

View on GitHub (pinned to 5903d58d58)

Solutions

1. Pass an actual Worker instance: new Worker(new URL('pdf.worker.min.mjs', import.meta.url), { type: 'module' }).
2. Pass null to clear the port and let PDF.js spawn its own worker from workerSrc.
3. Ensure the Worker global is defined in the environment (it is not in pure Node without a shim).

Example fix

// before
GlobalWorkerOptions.workerPort = myMessagePort;
// after
GlobalWorkerOptions.workerPort = new Worker(new URL('pdf.worker.min.mjs', import.meta.url), { type: 'module' });

if (val !== null && !(typeof Worker !== 'undefined' && val instanceof Worker)) {
  throw new Error('workerPort must be a Worker instance or null');
}
GlobalWorkerOptions.workerPort = val;

function isValidWorkerPort(val) {
  return val === null || (typeof Worker !== 'undefined' && val instanceof Worker);
}

When it happens

Trigger: GlobalWorkerOptions.workerPort = <not a Worker and not null> (e.g. a MessagePort, a worker factory, an object literal).

Common situations: Confusing Worker with MessagePort; assigning a function that creates a worker instead of the worker instance; passing a worker from a different realm/blob that fails the instanceof check.

Related errors

• Invalid `workerSrc` type.
• Built-in CMap parameters are not provided.
• No "GlobalWorkerOptions.workerSrc" specified.
• `BinaryDataFactory` not initialized, see the `useWorkerFetch
• PageViewport: Invalid rotation, must be a multiple of 90 deg

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