Common Issues

This article lists some of the most common issues you might encounter while integrating PSPDFKit for Web.

Styling Issues

When you override styling with general selectors (like svg, img, and div), especially in combination with !important, please be aware 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.

“Refused to Apply Style from CSS File Because Its MIME Type Is Not a Supported Stylesheet MIME Type” Error

This error occurs when — while fetching custom stylesheets — the assets server responds without the proper MIME header set, or if instead of responding with the CSS content, it responds with an HTML page (e.g. the path to the stylesheet is wrong and the server is returning a fallback 404 HTML page instead).

Please take a look at this Stack Overflow post for possible solutions.

The Mounting Container Has No Width/Height

PSPDFKit for Web requires an explicit width and height for the used container.

To work with your responsive designs, the width or height can be set to 100 percent. However, the height can be set to 100% only if the parent element has a height that isn’t set to auto. Otherwise, the height of your container will be resolved to 0px and you’ll get an error: “The mounting container has no height.” To fix this issue without changing the parent height, use 100vh, which represents 100 percent of the full viewport height.

Invalid Token

When receiving the “Invalid Token” error, 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:

/* 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);
}

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 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:

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:

* {
  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:

Unhandled promise rejection TypeError: Response has unsupported MIME type

Packages like serve, which set the correct Content-Type for WebAssembly files and are easy to get running, can be used to avoid such errors.

You can install serve as a project dependency with npm or yarn, and then you can run it from the project folder:

npm install serve
# This will make the current directory contents available through `http://0.0.0.0:5000`.
npx serve

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():

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.

Building Angular for Production with Source Maps

When building your Angular application for production with source maps enabled, your build might hang for several minutes while building ./node_modules/pspdfkit/dist/pspdfkit.js.

To make your build fast again, disable Angular’s build optimizer. Setting the buildOptimizer option to false in the production settings of angular.json will do the trick:

{
  "projects": {
    "<my-project>": {
      "architect": {
        "build": {
          "configurations": {
            "production": {
-             "buildOptimizer": true
+             "buildOptimizer": false
            }
          }
        }
      }
    }
  }
}

Angular App Not Working as Expected in Production

This might happen when Angular tries to optimize the already optimized PSPDFKit library. In order to fix this, we have to exclude PSPDFKit from Angular’s optimizer. This can be done by using PSPDFKit as a UMD module. To do this, make the following change in your angular.json file:

{
+   "scripts": ["./node_modules/pspdfkit/dist/pspdfkit.js"]
}

Now you can access PSPDFKit using window.PSPDFKit instead of importing it as a CommonJS/ES module.

Can I Open Local or Remote Files via URL?

Due to security concerns, web browsers do not allow fetch() and XMLHttpRequest APIs to access the local file system or other domains. 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:

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

A similar error might occur when trying to open a PDF document that is hosted on another domain. In order for PSPDFKit for Web to load such a file, the host server must set proper Cross-Origin Resource Sharing (CORS) headers.

If you don’t have control over the target server, you can use a local proxy to it to access the documents.

“Tainted Canvases May Not Be Exported” and “The Operation Is Insecure” Errors

You might see one of the following errors pop up during PSPDFKit’s initialization.

Google Chrome:

DOMException: Failed to execute 'toDataURL' on 'HTMLCanvasElement': Tainted canvases may not be exported.

Firefox/Safari:

SecurityError: The operation is insecure.

In such a scenario, it could be that you’re trying to load a cross-origin image from a PSPDFKit.Configuration#renderPageCallback definition. If that’s the case, please make sure to set the crossOrigin property of the HTMLImageElement instance to anonymous before setting its src:

const img = document.createElement("img");
img.crossOrigin = "anonymous";
img.src = "https://example.com/myimage.png";

PSPDFKit.load({
  renderPageCallback(ctx, pageIndex, pageSize) {
    ctx.drawImage(
      img,
      (pageSize.width - size) / 2,
      (pageSize.height - size) / 2
    );
  }
  // ...
});

“Content Security Policy: The page’s settings blocked the loading of a resource at inline” Errors

If you’re using a Content Security Policy (CSP) to secure your webpage, make sure you’re using the following options to allow our WASM Web Worker to operate:

script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval';
worker-src blob:;

Version 2023.5.4 and prior have an extra requirement of unsafe-eval, so if you’re using older versions of PSPDFKit for Web, use the following options:

script-src 'self' 'unsafe-inline' 'unsafe-eval';
worker-src blob:;

If you require a stricter set of policies, it’s recommended you use PSPDFKit for Web Server-Backed, as it doesn’t use a WASM Web Worker.

IE 11 Issues

If you’re using IIS Server, make sure your server is configured to handle .mem files. In the case that the browser doesn’t support WebAssembly, we fall back to asm.js, and we provide a .mem file that our application loads during initialization. You can read more about how to allow this manually on the IIS website.

Warning

Internet Explorer 11 is no longer supported in our Web SDK as of version 2022.5. Edge 18 is no longer supported in our Web SDK as of version 2023.2.

Chunk Failing to Load

If your browser throws a “414 Request-URI Too Large” error or can’t load the chunk because of the wrong URL, please pass the baseUrl option in the configuration object.

Digital Signature Fails to Verify on PSPDFKit but Adobe Acrobat Is Able to Verify It Correctly

One possible reason for PSPDFKit not being able to correctly verify digital signatures on a document is if the required trusted root certificates aren’t loaded when initializing a PSPDFKit for Web instance.

The reason Adobe Acrobat is able to correctly verify the document on the host machine is because it has access to certificates installed on the host. Additionally, it ships with a built-in list of certificates known as the Adobe Approved Trust List (AATL).

Please refer to our How to Create Custom Certificate Sets guide to learn how to use your trusted root certificate files for digital signature validation on both Standalone and Server-backed deployments.

Reserved Size Is Not Enough to Contain the Signature

If, while signing a document, you receive an error in the console that says “Cannot add the container structure because the reserved size is not enough to contain the signature,” it means the certificate size is bigger than we expected. You can solve this by passing a custom placeholderSize while calling instance.signDocument. placeholderSize is used to override the default size that’s reserved for the signature container. You can read more about it in our Digital Signatures guide.

NetworkError When Attempting to Fetch Resource

Browsers sometimes throw an error when a fetch() call is interrupted. The specific error depends on the browser. Here are some examples of this error that we observed in various browsers:

  • Chrome — TypeError: Failed to fetch

  • Firefox — TypeError: NetworkError when attempting to fetch resource

  • Safari — TypeError: cancelled

This can happen when the network is down or when a user clicks the stop loading button while the API request is in progress. This means that if you’re getting random reports with these errors, you can usually ignore them as they’re most likely the result of a usual workflow.

Keep in mind that these errors could also indicate a possible CORS error — “Failed to fetch” errors can also be generated in the case of failed fetch requests due to misconfigured CORS headers. You should investigate if you’re getting these errors without any known reason that could have led to canceling the fetch() calls.

Network error net::ERR_BLOCKED_BY_CLIENT

Unspecified network errors such as net::ERR_BLOCKED_BY_CLIENT can be thrown when the client blocks network requests. Possible culprits could be browser extensions such as AdBlock or Ghostery, or similar privacy tools. Another cause could be an antivirus or anti-spyware software running on a user’s device or a network proxy.

You can check if the browser extension is causing your issues by running in an incognito mode (but make sure to not have extensions enabled) or in another browser with no extensions installed. If the issue is caused by system- or network-wide antivirus/privacy software, you’ll need to find a way to disable it, or preferably, run it on a separate machine or a separate network.

Inaccurate Text Selection via UI

Our viewer renders PDF pages as images. When there’s text in the page, this text is rendered as part of the image, using the original font. To enable text selection, we then overlay the same text in HTML but make it transparent using CSS. The only problem with this approach is that the browser might not ship the original fonts in the PDF, in which case it’ll fall back to a generic font. In this case, manual text selection might be not be accurate. This is a known issue, and we’re exploring solutions to improve this behavior in the future.