mozilla/pdf.js · error · Error

PDFWorker.create - the worker is being destroyed. Please rem

Error message

PDFWorker.create - the worker is being destroyed.
Please remember to await `PDFDocumentLoadingTask.destroy()`-calls.

What it means

A generic Error from PDFWorker.create: the requested port maps to a cached PDFWorker whose _pendingDestroy flag is set, meaning destroy() was called on it but has not finished. Reusing a half-destroyed worker would race the teardown. The message explicitly reminds the caller to await PDFDocumentLoadingTask.destroy().

Source

Thrown at src/display/api.js:2360

    this.#webWorker?.terminate();
    this.#webWorker = null;

    PDFWorker.#workerPorts.delete(this.#port);
    this.#port = null;

    this.#messageHandler?.destroy();
    this.#messageHandler = null;
  }

  /**
   * @param {PDFWorkerParameters} params - The worker initialization parameters.
   * @returns {PDFWorker}
   */
  static create(params) {
    const cachedPort = this.#workerPorts.get(params?.port);
    if (cachedPort) {
      if (cachedPort._pendingDestroy) {
        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.');

View on GitHub (pinned to 5903d58d58)

Solutions

1. Always await worker.destroy() (and any loadingTask.destroy() that owns it) before creating a new PDFWorker on the same port.
2. Sequence teardown and recreation in an async function so the next create runs after destroy resolves.
3. If you cannot await, allocate a fresh port/Worker for the new PDFWorker instead of reusing.

Example fix

// before
worker.destroy(); // not awaited
pdfjsLib.PDFWorker.create({ port }); // throws

// after
await worker.destroy();
pdfjsLib.PDFWorker.create({ port });

// Ensure the cached worker is not mid-destroy before reuse.
const cached = pdfjsLib.PDFWorker._workerPorts?.get?.(port);
if (cached && cached._pendingDestroy) {
  throw new Error('Await the previous worker.destroy() first');
}

When it happens

Trigger: Calling PDFWorker.create({port}) (or getDocument with that port via GlobalWorkerOptions.workerPort) after a previous worker.destroy() on the same port without awaiting its completion; rapid create/destroy churn on a shared port.

Common situations: SPA teardown/remount cycles that destroy and immediately recreate a worker; forgetting that destroy() is asynchronous; fire-and-forget cleanup handlers.

Related errors

• Worker was destroyed
• Cannot use more than one PDFWorker per port.
• Worker was destroyed.
• Loading aborted
• Transport destroyed

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