What causes "Invalid `workerSrc` type." in mozilla/pdf.js?

Set workerSrc to a string URL of the worker bundle.

mozilla/pdf.js · error · Error

Invalid `workerSrc` type.

Error message

Invalid `workerSrc` type.

What it means

Thrown by the GlobalWorkerOptions.workerSrc setter when the value is not a string. workerSrc must be a URL string pointing at the worker script so PDF.js can spawn the worker. Non-string values (URL objects, modules, numbers, undefined) are rejected because they cannot be used to construct a Worker.

Source

Thrown at src/display/worker_options.js:58

  }

  /**
   * @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.
   */
  static set workerSrc(val) {
    if (typeof val !== "string") {
      throw new Error("Invalid `workerSrc` type.");
    }
    this.#src = val;
  }
}

export { GlobalWorkerOptions };

View on GitHub (pinned to 5903d58d58)

Solutions

Set workerSrc to a string URL of the worker bundle.
If using a URL object, assign url.href (a string).
Use a bundler helper (e.g. Vite's ?worker or Webpack's worker-loader) and pass the resolved string URL.

Example fix

// before
GlobalWorkerOptions.workerSrc = new URL('pdf.worker.min.mjs', import.meta.url);
// after
GlobalWorkerOptions.workerSrc = new URL('pdf.worker.min.mjs', import.meta.url).href;

Defensive patterns

Strategy: validation

Validate before calling

if (typeof val !== 'string') {
  throw new Error('workerSrc must be a string URL');
}
GlobalWorkerOptions.workerSrc = val;

Type guard

function isValidWorkerSrc(val) {
  return typeof val === 'string' && val.length > 0;
}

Prevention

Always set workerSrc to a string URL of the worker bundle.
If you hold a URL object, assign url.href.
Use bundler helpers that resolve to a string URL.
Never assign a module namespace or undefined to workerSrc.

When it happens

Trigger: GlobalWorkerOptions.workerSrc = <non-string> (e.g. a URL object, a module namespace, undefined).

Common situations: Assigning a `new URL(...)` object instead of its .href; importing the worker as a module and assigning the namespace; forgetting to set workerSrc at all in an environment where it is required.

Related errors

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