mozilla/pdf.js · error · Error

No "GlobalWorkerOptions.workerSrc" specified.

Error message

No "GlobalWorkerOptions.workerSrc" specified.

What it means

A generic Error from the static PDFWorker.workerSrc getter: GlobalWorkerOptions.workerSrc is empty. The worker source URL is required to spawn the real Web Worker (the entry that contains the full pdf.js core). Without it the #initialize path cannot construct new Worker(workerSrc). The exception is not thrown if a workerPort is provided (which bypasses workerSrc) or if the fake/loopback worker path is used.

Source

Thrown at src/display/api.js:2378

        throw new Error(
          "PDFWorker.create - the worker is being destroyed.\n" +
            "Please remember to await `PDFDocumentLoadingTask.destroy()`-calls."
        );
      }
      return cachedPort;
    }
    return new PDFWorker(params);
  }

  /**
   * The current `workerSrc`, when it exists.
   * @type {string}
   */
  static get workerSrc() {
    if (GlobalWorkerOptions.workerSrc) {
      return GlobalWorkerOptions.workerSrc;
    }
    throw new Error('No "GlobalWorkerOptions.workerSrc" specified.');
  }

  static get #mainThreadWorkerMessageHandler() {
    try {
      return globalThis.pdfjsWorker?.WorkerMessageHandler || null;
    } catch {
      return null;
    }
  }

  // Loads worker code into the main-thread.
  static get _setupFakeWorkerGlobal() {
    const loader = async () => {
      if (this.#mainThreadWorkerMessageHandler) {
        // The worker was already loaded using e.g. a `<script>` tag.
        return this.#mainThreadWorkerMessageHandler;
      }
      const worker =

View on GitHub (pinned to 5903d58d58)

Solutions

1. Set pdfjsLib.GlobalWorkerOptions.workerSrc to the URL/path of pdf.worker.js (or .mjs) before calling getDocument.
2. When bundling, import the worker URL explicitly (e.g. workerSrc = new URL('pdfjs-dist/build/pdf.worker.mjs', import.meta.url)).
3. Provide a workerPort via GlobalWorkerOptions.workerPort if you manage the Worker yourself.
4. For Node/SSR, set useWorkerFetch/disabled worker as appropriate.

Example fix

// before
import * as pdfjsLib from 'pdfjs-dist';
pdfjsLib.getDocument({ url }); // throws: workerSrc not set

// after
import * as pdfjsLib from 'pdfjs-dist';
pdfjsLib.GlobalWorkerOptions.workerSrc =
  new URL('pdfjs-dist/build/pdf.worker.mjs', import.meta.url).toString();
pdfjsLib.getDocument({ url });

if (!pdfjsLib.GlobalWorkerOptions.workerSrc && !pdfjsLib.GlobalWorkerOptions.workerPort) {
  throw new Error('Set GlobalWorkerOptions.workerSrc before calling getDocument');
}
pdfjsLib.GlobalWorkerOptions.workerSrc ||=
  new URL('pdfjs-dist/build/pdf.worker.mjs', import.meta.url).toString();

When it happens

Trigger: Calling getDocument() without first assigning pdfjsLib.GlobalWorkerOptions.workerSrc, and without providing a worker/workerPort; bundler setups where the worker URL was tree-shaken or not copied; ES-module imports that forgot to set workerSrc.

Common situations: First-time integrations; webpack/vite configs that did not emit the worker bundle; CDN migrations that changed the path; SSR/Node usage without setting workerSrc or disabling the worker.

Related errors

• Built-in CMap parameters are not provided.
• `BinaryDataFactory` not initialized, see the `useWorkerFetch
• Invalid `workerPort` type.
• Invalid `workerSrc` type.
• Unknown CMap name: ${name}

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