mozilla/pdf.js · critical · Error

The API version "${version}" does not match the Viewer versi

Error message

The API version "${version}" does not match the Viewer version "${viewerVersion}".

What it means

Thrown by the PDFViewer constructor when the API module's version (imported 'version') does not equal the viewer module's BUNDLE_VERSION (build-time constant). PDF.js enforces that the display API and viewer UI ship together to prevent subtle ABI/contract mismatches.

Source

Thrown at web/pdf_viewer.js:314

  #textLayerMode = TextLayerMode.ENABLE;

  #viewerAlert = null;

  #copiedPageViews = null;

  #savedPageViews = null;

  #deletedPageNumbers = null;

  /**
   * @param {PDFViewerOptions} options
   */
  constructor(options) {
    const viewerVersion =
      typeof PDFJSDev !== "undefined" ? PDFJSDev.eval("BUNDLE_VERSION") : null;
    if (version !== viewerVersion) {
      throw new Error(
        `The API version "${version}" does not match the Viewer version "${viewerVersion}".`
      );
    }

    this.container = options.container;
    this.viewer = options.viewer || options.container.firstElementChild;
    this.#viewerAlert = options.viewerAlert || null;

    if (typeof PDFJSDev === "undefined" || PDFJSDev.test("GENERIC")) {
      if (this.container?.tagName !== "DIV" || this.viewer?.tagName !== "DIV") {
        throw new Error("Invalid `container` and/or `viewer` option.");
      }

      if (
        this.container.offsetParent &&
        getComputedStyle(this.container).position !== "absolute"
      ) {
        throw new Error("The `container` must be absolutely positioned.");

View on GitHub (pinned to 5903d58d58)

Solutions

1. Use a single coherent pdfjs-dist release for both the API (pdf.js) and viewer (pdf_viewer.js).
2. Rebuild via 'npx gulp generic' or 'npx gulp dist' so BUNDLE_VERSION matches the API version.
3. Clear node_modules and dist caches; pin pdfjs-dist to one exact version in package.json.

Example fix

// before - mixed versions
import { version } from 'pdfjs-dist/old/build/pdf.js';
import { PDFViewer } from 'pdfjs-dist/web/pdf_viewer.js'; // different release

// after - single release
import { version } from 'pdfjs-dist/build/pdf.mjs';
import { PDFViewer } from 'pdfjs-dist/web/pdf_viewer.mjs'; // same release

// Ensure the API and viewer come from the same pdfjs-dist release.
import { version as apiVersion } from 'pdfjs-dist/build/pdf.mjs';
// viewer must be imported from the same installed package version.

When it happens

Trigger: Constructing new PDFViewer(...) where the loaded pdf.js API version differs from pdf_viewer.js's bundled version. Happens when mixing dist files from different releases or when PDFJSDev.eval('BUNDLE_VERSION') resolves to a mismatched value.

Common situations: Bundling pdf.js API from one npm release and the viewer components from another; partial upgrades; stale cached dist artifacts; CDN pinning to different tags.

Related errors

• Invalid `container` and/or `viewer` option.
• --index was given without a value
• coverage_search failed (exit code ${result.status})
• No default preferences found in "${dir}".
• Unknown CMap name: ${name}

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