Common Issues


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).

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

Accessing the Error Log

PSPDFKit Server will pipe useful logging information to the attached standard streams, stdout and stderr. When you submit a bug report, always make sure to include the relevant lines.

Accessing this information depends on your deployment option. If you have started PSPDFKit Server locally, you can open the terminal window the server is running in to see the output.

In production, you can use docker logs or a similar tool, depending on your deployment option.

If the log does not contain useful information, you can try to set the log level to debug with the LOG_LEVEL environment variable.

Invalid Token

When receiving the “Invalid Token” error, you can debug and verify your token on 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.

Running PSPDFKit Server with Docker Toolbox

Docker Toolbox is for older versions of Mac and Windows, and we recommend updating to Docker for Mac or Docker for Windows if possible.

When running PSPDFKit Server on Docker Toolbox, it won’t be reachable with localhost, because Docker Toolbox is running a Linux VM in VirtualBox.

To get the IP address of your Docker machine, which can be used instead of localhost, run the following:

docker-machine ip

The Server Does Not Start Due to a Pending Migration Error

This error occurs when the server is not able to do database migrations. Make sure you use the recommended version of Postgres.

Issue When Running on Windows: Pulling from PSPDFKit Image Operating System “Linux” Cannot Be Used on This Platform

This may happen when your Docker engine is configured to run Windows containers and PSPDFKit Server is packaged as a Linux image. We recommend installing Docker for Windows, which adds a thin VM that can run Linux containers. See this issue on Docker’s issue tracker for more technical details.

Learn more in our Docker guide.

exdev Error When Copying Assets

In certain cases, you might encounter errors like this:

[error] 2020-11-19 21:05:39.193 Failed to copy asset
    :exdev pid=<0.2505.0>

[error] 2020-11-19 21:05:39.193 Error accessing cache: storage_failure. Please contact pid=<0.3002.0>

The :exdev error code you see here means the assets/tmp/ and assets/cache/ folders are not on the same mountpoint. This can happen when you’re configuring a volume mount at /srv/pspdfkit/assets/cache and it points to a different disk than the one Docker is running off of. It’s thrown because, despite the error log saying we copy the asset, for efficiency reasons, we only move it from the tmp folder to the cache folder.

The documentation for the Linux rename function has more information:

EXDEV  oldpath and newpath are not on the same mounted filesystem.
       (Linux permits a filesystem to be mounted at multiple points,
       but rename() does not work across different mount points, even
       if the same filesystem is mounted on both.)

Bug Reports

If you experience an issue you believe is related to PSPDFKit Server, please report this to us. When reporting, please give us as much information as possible so that we can help you more effectively. Refer to our Bug Reporting guide for more details.