Handling PSPDFKit Server and Web SDK Version Mismatch


PSPDFKit Server has been deprecated and replaced by PSPDFKit Document Engine. All PSPDFKit Server and PSPDFKit for Web Server-Backed licenses will work as before and be supported until 15 May 2024 (we will contact you about license migration). To start using Document Engine, refer to the migration guide. With Document Engine, you’ll have access to robust new capabilities (read the blog for more information).

Question: How do I handle version mismatch between PSPDFKit Server and Web SDK?


PSPDFKit Server requires that the instance of Web SDK connecting to it has the exact same version as it does. When the versions do not match, the Server returns an error and SDK won’t load properly.

If you’re using pspdfkit.js asset served by the Server, this situation should not happen, as we make sure that the asset cached by the browser is invalidated when the Server is upgraded. However, in case you’re using Web SDK pulled from NPM and bundling it with your frontend application, it might happen that the SDK and the Server are upgraded independently, in which case the version mismatch error will show up.

The potential solution is feasible only if your PDF files are served by other service, different from PSPDFKit Server. In that case, when the version mismatch error occurs, you may fall back to using SDK in standalone mode, and load the file directly from the other service. While the changes made to the file won’t be persisted, this allows you to display the file to your users. You can use the following snippet to detect a version mismatch error:

  .then(() => { console.log('connected to the server')})
  .catch(error => {
    if (/Client version does not match the Server version/.test(error.message)) {
      // fall back to standalone code