Troubleshooting

Common Issues

Styling Issues

When you override styling with general selectors (like svg, img, div), especially in combination with !important, please be aware that this could cause errors in PSPDFKit for Web and we can’t guarantee correct rendering.

The easiest way to debug styling issues is to remove your own CSS from the site and see if the styling issue in PSPDFKit for Web remains. If the issues are gone after removing your CSS, add your CSS file again and open the developer tools of your browser to inspect elements that have issues. Toggle off stylings that get added by your CSS file — by eliminating each CSS attribute, you’ll find out what causes the problem.

If you want to override certain styles in PSPDFKit for Web, please use our public CSS classes.

The Mounting Container Has No Width / Height

PSPDFKit for Web requires the used container to have an explicit width and height. The width or height can be set to 100% and PSPDFKit for Web works great with your responsive designs, but it needs a width or height that is greater than 0px.

Invalid Token

When receiving the Error “Invalid Token,” you can debug and verify your token on jwt.io. You’ll also get an error in the server log, where you can see if the token has expired or if the user has no access for the given document.

Customizing the Fit-to-Page and Fit-to-Width Toggle Button

Since we’re using a toggle button to switch between the fit-to-page and fit-to-width zoom modes, we need to use some CSS to overwrite the styles and define a different icon for each zoom mode:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
/* We're removing the shown svg on both buttons. */
.PSPDFKit-Toolbar-Button-Fit-To-Page svg,
.PSPDFKit-Toolbar-Button-Fit-To-Width svg {
  content: "";
}

/* Then we set our own icons. */
.PSPDFKit-Toolbar-Button-Fit-To-Page span {
  content: url(my-custom-fit-to-page-icon.svg);
}

.PSPDFKit-Toolbar-Button-Fit-To-Width span {
  content: url(my-custom-fit-to-width-icon.svg);
}

Bug Reports

If you experience a bug you believe is related to PSPDFKit for Web, please report this to us. When reporting a bug, please use the built-in debug output and send us a screenshot of your page.

To use the built-in debug output, use the search feature (this can be accessed via CMD/Ctrl + F or by clicking on the magnifying icon in the toolbar) and type in pspdfkit:debug. You will then see a bug icon in the toolbar. Click on it and select Download Debug Output, which downloads a text file with information about the current PSPDFKit for Web license, device information, an HTML snapshot, and the CSS. Please attach this text file when reporting a bug. Feel free to remove sensitive information from the log file.

Download Debug Output

Safari does not support automatically downloading the generated file. Please press CMD + S to save the file to the disk manually before attaching it to your support request.


Page Is Zoomed When Using the Trackpad

In Microsoft Edge, the webpage is zoomed when using the pinch-to-zoom gesture on the trackpad. This is because of a different way that trackpad gestures are handled. To prevent this, you can still disable the native browser zooming by setting the -ms-content-zooming property to none in the body element of your page:

1
2
3
body {
  -ms-content-zooming: none;
}

In other browsers, pinch-to-zoom can be prevented by defining the allowed touch actions. By only allowing pan-x and pan-y, you can prevent the browser from handling pinch and double-tap gestures. Unfortunately, the safest way to prevent this is by defining it for every element. Otherwise, pinch gestures could be emitted by all elements:

1
2
3
* {
  touch-actions: pan-x pan-y;
}

“Response Has Unsupported MIME Type” Error

When using the standalone deployment in browsers that support WebAssembly streaming instantiation, the pspdfkit.wasm file must be served with the correct content type header: Content-Type: application/wasm. When the server is not configured to do so, you might get an exception:

1
Unhandled promise rejection TypeError: Response has unsupported MIME type

Unfortunately, packages like [email protected] (and below) don’t yet set the right Content-Type. If you do rely on such packages, we suggest that you pin the version of the underlying MIME library (for mime, the minimum required version would be 1.6.0).

Workaround by disabling streaming instantiation

We highly recommend that you add support for the proper WebAssembly MIME type to your web server due to reasons outlined in this blog post. If you do not have the resources to do so, you can also disable streaming instantiation by adding the following option to the configuration object passed to PSPDFKit.load():

1
2
3
4
PSPDFKit.load({
  disableWebAssemblyStreaming: true
  // ... other options
});

Why Do I Have to Manually Copy Files from node_modules into My App?

PSPDFKit is bundler agnostic (for the same reasons it is framework agnostic). In fact, it can even be used without a bundler, and PSPDFKit’s assets can be referenced via link and script tags.

Additionally, we split our codebase into multiple files so that specific pieces are loaded lazily, i.e. only when they are used. If we were to provide a single file bundle, its size would be extremely large, and most of the time, this is unacceptable.

The main entry point, pspdfkit.js, is usually bundled automatically by tools. However, the pspdfkit-lib additional assets need to be copied manually since the host application is not aware of them being loaded lazily.


I18n: Cannot find translations for "en". Please retry or add them manually to PSPDFKit.I18n.messages["en"]

Translations and other assets like the CSS for PSPDFKit for Web are located in the pspdfkit-lib folder. When this folder is not copied to the same location of your application file that includes pspdfkit, then PSPDFKit for Web is not able to locate those assets. This is usually an issue with Standalone, since the Server is already preconfigured to serve those files correctly.

Please refer to our guide to find out how to copy the PSPDFKit for Web assets.


Copying the PSPDFKit for Web Assets in Angular

In order to integrate PSPDFKit for Web with Angular, you need to add the following in angular.json under the assets option:

Copy
1
2
3
4
5
6
7
8
9
10
{
  "assets": [
    "src/assets",
+    {
+      "glob": "**/*",
+      "input": "./node_modules/pspdfkit/dist/pspdfkit-lib/",
+      "output": "./assets/pspdfkit-lib/"
+    }
  ]
}

Then, in your application component where you initialize PSPDFKit, you need to set the baseUrl accordingly:

1
2
3
4
PSPDFKit.load({
  baseUrl: location.protocol + "//" + location.host + "/assets/"
  // ...
});

Can I Open Local Files (file:// URLs)?

Due to security concerns, web browsers do not allow fetch() and XMLHttpRequest APIs to access the local file system. Since we need those APIs in order to load required artifacts and PDF files, PSPDFKit for Web also requires a lightweight web server as outlined in our standalone integration guides.

An example error for using fetch() with a file:// URL looks like this:

1
Fetch API cannot load file:///example.pdf. URL scheme must be "http" or "https" for CORS request.