{"record":{"id":"58e39d78e93d78cf","repo":"mozilla/pdf.js","slug":"the-api-version-version-does-not-match-the-vi","errorCode":null,"errorMessage":"The API version \"${version}\" does not match the Viewer version \"${viewerVersion}\".","messagePattern":"The API version \"(.+?)\" does not match the Viewer version \"(.+?)\"\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"web/pdf_viewer.js","lineNumber":314,"sourceCode":"\n  #textLayerMode = TextLayerMode.ENABLE;\n\n  #viewerAlert = null;\n\n  #copiedPageViews = null;\n\n  #savedPageViews = null;\n\n  #deletedPageNumbers = null;\n\n  /**\n   * @param {PDFViewerOptions} options\n   */\n  constructor(options) {\n    const viewerVersion =\n      typeof PDFJSDev !== \"undefined\" ? PDFJSDev.eval(\"BUNDLE_VERSION\") : null;\n    if (version !== viewerVersion) {\n      throw new Error(\n        `The API version \"${version}\" does not match the Viewer version \"${viewerVersion}\".`\n      );\n    }\n\n    this.container = options.container;\n    this.viewer = options.viewer || options.container.firstElementChild;\n    this.#viewerAlert = options.viewerAlert || null;\n\n    if (typeof PDFJSDev === \"undefined\" || PDFJSDev.test(\"GENERIC\")) {\n      if (this.container?.tagName !== \"DIV\" || this.viewer?.tagName !== \"DIV\") {\n        throw new Error(\"Invalid `container` and/or `viewer` option.\");\n      }\n\n      if (\n        this.container.offsetParent &&\n        getComputedStyle(this.container).position !== \"absolute\"\n      ) {\n        throw new Error(\"The `container` must be absolutely positioned.\");","sourceCodeStart":296,"sourceCodeEnd":332,"githubUrl":"https://github.com/mozilla/pdf.js/blob/5903d58d58e4dd9ce6ffa3834aea8480f06b4ada/web/pdf_viewer.js#L296-L332","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a single coherent pdfjs-dist release for both the API (pdf.js) and viewer (pdf_viewer.js).","Rebuild via 'npx gulp generic' or 'npx gulp dist' so BUNDLE_VERSION matches the API version.","Clear node_modules and dist caches; pin pdfjs-dist to one exact version in package.json."],"exampleFix":"// before - mixed versions\nimport { version } from 'pdfjs-dist/old/build/pdf.js';\nimport { PDFViewer } from 'pdfjs-dist/web/pdf_viewer.js'; // different release\n\n// after - single release\nimport { version } from 'pdfjs-dist/build/pdf.mjs';\nimport { PDFViewer } from 'pdfjs-dist/web/pdf_viewer.mjs'; // same release","handlingStrategy":"validation","validationCode":"// Ensure the API and viewer come from the same pdfjs-dist release.\nimport { version as apiVersion } from 'pdfjs-dist/build/pdf.mjs';\n// viewer must be imported from the same installed package version.","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin pdfjs-dist to one exact version in package.json.","Never mix API and viewer files from different releases or CDNs.","Rebuild dist with gulp after upgrades so BUNDLE_VERSION matches."],"tags":["version","build","configuration","constructor"],"backgroundTag":null,"analyzedSha":"5903d58d58e4dd9ce6ffa3834aea8480f06b4ada","analyzedAt":"2026-08-13T02:28:27.364Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}