mozilla/pdf.js · error · Error

`BinaryDataFactory` not initialized, see the `useWorkerFetch

Error message

`BinaryDataFactory` not initialized, see the `useWorkerFetch` parameter.

What it means

A generic Error in the FetchBinaryData handler: the worker requested binary data via the main thread, but transportFactory.binaryDataFactory is null. binaryDataFactory is null when useWorkerFetch is true (MozCentral, or the generic build when all of cMapUrl, standardFontDataUrl, wasmUrl etc. are valid fetch URLs), because under useWorkerFetch the worker fetches directly and the main-thread factory is intentionally not built. Reaching this handler means the configuration diverged: useWorkerFetch said 'no main-thread factory' yet the worker still routed a fetch to main.

Source

Thrown at src/display/api.js:2917

        default:
          throw new Error(`Got unknown object type ${type}`);
      }
    });

    messageHandler.on("DocProgress", data => {
      if (this.destroyed) {
        return; // Ignore any pending requests if the worker was terminated.
      }
      this.#onProgress(data);
    });

    if (typeof PDFJSDev === "undefined" || !PDFJSDev.test("MOZCENTRAL")) {
      messageHandler.on("FetchBinaryData", async data => {
        if (this.destroyed) {
          throw new Error("Worker was destroyed.");
        }
        if (!this.binaryDataFactory) {
          throw new Error(
            "`BinaryDataFactory` not initialized, see the `useWorkerFetch` parameter."
          );
        }
        return this.binaryDataFactory.fetch(data);
      });
    }
  }

  getData() {
    return this.messageHandler.sendWithPromise("GetData", null);
  }

  saveDocument() {
    if (this.annotationStorage.size <= 0) {
      warn(
        "saveDocument called while `annotationStorage` is empty, " +
          "please use the getData-method instead."
      );

View on GitHub (pinned to 5903d58d58)

Solutions

1. Ensure pdf.js worker and API builds are the same version (mismatched versions can route messages the wrong way).
2. If you need main-thread binary fetching, set useWorkerFetch:false and provide cMapUrl/standardFontDataUrl/wasmUrl plus a binaryDataFactory.
3. Provide all required URLs (cMapUrl, cMapPacked, standardFontDataUrl, wasmUrl) consistently so useWorkerFetch resolves the same way on both sides.

// Keep useWorkerFetch consistent with the URLs you provide.
const hasAllUrls = src.cMapUrl && src.standardFontDataUrl && src.wasmUrl;
if (!hasAllUrls && src.useWorkerFetch) {
  src.useWorkerFetch = false; // let pdf.js build the main-thread factory
}

When it happens

Trigger: A build/config where useWorkerFetch resolved true (so binaryDataFactory is null) but the worker still sent FetchBinaryData to the main thread; custom WorkerTransport setups that override useWorkerFetch incorrectly; partial factory configuration where only some URLs are valid.

Common situations: Misconfigured cMapUrl/standardFontDataUrl/wasmUrl; embedding pdf.js with a custom transport that doesn't wire up the factory; version mismatches between worker and API.

Related errors

• Built-in CMap parameters are not provided.
• No "GlobalWorkerOptions.workerSrc" specified.
• Worker was destroyed.
• Invalid `workerPort` type.
• Invalid `workerSrc` type.

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