License Troubleshooting | Web

PSPDFKit for Web is a commercial SDK and requires a license to work. We issue one license per explicit domain. Contact [email protected] if you have any questions related to your license.

Domain Registration and Subdomain Use

The domain you register must completely match the domain where the SDK is used, including any subdomains. To put it in the context of the browser window, the domain you register in the license must match the domain in the browser URL bar exactly when your application is loaded.

Example: You register weylandcorp.com but then use www.weylandcorp.com. In this case, the license will not work. Fix: You need to redirect www.weylandcorp.com to weylandcorp.com.

Example: You register www.weylandcorp.com but then use spaceship.weylandcorp.com. In this case, the license will not work. Fix: Register spaceship.weylandcorp.com instead.

Example: You register pdf.yutanicorp.com and show documents via viewer.yutanicorp.com/pdf/eca. This is incorrect, since the subdomains don’t match (pdf vs viewer). Fix: Register viewer.yutanicorp.com instead.

Example: Your production domain is science.weylandcorp.com but you’re developing via bg386-dev.weylandcorp.com. The production license won’t work on the development domain, as the domain doesn’t match. Fix: Register an additional developer license via the PSPDFKit Portal for the bg386-dev.weylandcorp.com domain to run the dev instance.

Example: Your production domain is science.weylandcorp.com and you’re hosting Document Engine at pspdfkit.weylandcorp.com. Fix: In this case, you need to register science.weylandcorp.com, since the domain where the Web SDK is used is the relevant part. You also need to provide the serverUrl when initializing PSPDFKit to inform it that Document Engine isn’t running under the same domain.

Example: You registered your production domain but run into issues with your local development. Log in to the PSPDFKit Portal and request a license for localhost via the Request License Key for Web Beta Usage button.

License Types

PSPDFKit for Web can be used and licensed in two variants: standalone or server-based deployment. Licensing is different depending on your choice.

Standalone Deployment (WebAssembly)

Standalone deployment uses a license key, which is passed as part of the PSPDFKit.load() call:

// Activate PSPDFKit for `yourdomain.com`.
PSPDFKit.load({
  ...
  licenseKey: 'nX5NbnzGFzYhuWTje1LqC8hWYX1jP_WAqka-8-QcLZgcng4Je_N5got-bmUwN4iUsNIG1npc-HoH44LKxuQySy6P9JokAL0atlESXg8Xcs7fu7kCycgT64ehcgvSUmJpfSOXEs-4qtXWJe_wFPy8k1UI7iPFpMZohIlcGf5QufmFC9u-7fJXIfgihjDsqI7nHzFEjbIJ65k7c8xBb8dE_HhxMupbX-FwX4eKI7LwmR_imk5mPyyI18gRZi5ZSBjkWwAEcV4uKl5WorX4xCpiupXiK6C4-xboonMh_J421qGP7Hg5_4lVnUY08sTLzQMVh-JvPdbBT77mLhn-lBmtel2yAwpYk7zX7TrelRBK6Uj5YpjMpGfcv257WmfQvBYzUo7NsU7P1RQWN7jr8v64irZQ89DdDq6UkMhPnlF-zok16rIcVyY6R5qGBDBMItwAs1yr8DSVtmNeqy8ito7FYDH-j1C_bs-v4LEowKoUB-w60IUjHcmTGh1cNKRTAj4iWY03CpeYJPNc9mnygMJ7Fsk9hg==',
  ...
})

To get a domain license key, register your domain in the PSPDFKit Portal with the credentials you received from our sales team.

Web License Key

If you see an error, please check in the JavaScript Console for errors. (If you use Safari, use the Inspector.)

The most likely issues are a copy/paste issue where characters are missing, or using a key that doesn’t match your domain. If you’ve renewed your license recently, make sure you’re using the updated license key.

Please note that it’s not a security risk to use plain license keys on client-side code. License keys can’t be reused by third parties since they’re tied to your domain. Additionally, there’s no personal information linked to them.

Learn more about standalone licensing here.

Server-Based Deployment (Docker)

Server-based deployment uses an activation key rather than a license key. This key is passed as an environment variable for the server container.

For example, if you’re using Docker Compose, you can add the activation key to docker-compose.yml:

services:
  pspdfkit:
    image: pspdfkit/pspdfkit
    environment:
      ACTIVATION_KEY: obiWMzt3XouUsAiwyWGSrC7RMdSv5hME

To get a product key, register your domain on the PSPDFKit Portal with the credentials you received from our sales team.

Web License Key

The activation key is stored in the connected PostgreSQL database. If you accidentally purge the database, contact [email protected] to ask us to delete the current installation so that you can activate the new server installation. Once activated, you can no longer change the production key.

You should see the activation key only once: when you choose to activate a new installation via the Activate… button.

Once your installation is activated, the activation key is no longer valid, and you won’t see it in the PSPDFKit Portal again.

Learn more in our step-by-step guide to product activation.

Handling License Updates

For Server-based deployments, if you extended your license or changed its features or domains, you don’t need to replace the activation key. Instead, follow the steps in the Updating the Activated License guide.

Standalone-based deployments will require a new license key from the PSPDFKit Portal.

Error and Warning Messages

This section covers the error and warning messages you might receive, what they mean, and how to fix them.

Feature Missing

When you see the red warning message shown below, open the JavaScript Console to see the error details.

PSPDFKitError: Instant feature is not enabled on this server. please set instant to false

This occurs because you’re trying to connect the PSPDFKit for Web JavaScript library to a server with a component that isn’t included in your license.

Set the instant option to false in PSPDFKit.load(), or add the Instant component to your license.

Domain Mismatch (Standalone)

PSPDFKit Licensing Issue: Your license has been registered for a different bundle identifier: “some-domain.com” - not “actual-company-domain.com”. Each PSPDFKit license is only valid for one explicit bundle ID and one distribution method (Enterprise or public App Store). Please contact sales at [email protected] with your requirements for a new license

If you see this message, the domain you registered in the PSPDFKit Portal doesn’t match the domain where PSPDFKit for Web (Standalone) is used. We use the origin domain to check. This is the domain your website is served from (the domain you see in the browser).

If you need to be able to use your license with a domain like localhost or 127.0.0.1 for development or demo purposes, you can request a license key for beta use through the PSPDFKit Portal:

  1. Log in to the PSPDFKit Portal using your credentials.

  2. Press the Request License Key for Web Beta Usage button next to the Download PSPDFKit for Web button.

Request License Key for Web Beta usage button

  1. A dialog will appear for you to fill in. Please type your required bundle ID (i.e. localhost) and your reason for the request.

Request License Key for Web Beta usage dialog

  1. Confirm the request form filled-in data, and press Request License Key.

Request License Key for Web Beta usage dialog

  1. Once your request is sent, a message will appear acknowledging your request.

Request License Key for Web Beta usage dialog

Requests are reviewed and you’ll get an email about any status updates within 1–2 business days.

Unable to Request Beta License Key

“You must assign a production license key before requesting one for beta usage, so we can clearly see the relationship between them.”

Before requesting a license key for beta testing/development purposes, you must first register a production ID with a matching domain name. Once you’ve registered this, then the dialog for requesting development keys will be unlocked.

Domain Mismatch (Server)

An error occurred while connecting to Document Engine: Document Engine is not licensed from the origin actual-company-domain.com

This error is displayed when the domain registered in your license is different than the domain visible in the web browser displaying the page that loads the PSPDFKit for Web viewer.

Heads up: Domains that end with .local are meant for development/intranet only and should never be registered as production domains. If you have something like this, please ping our sales team so we can set this up for you. If you accidentally registered a .local domain as a production domain, ping our team with the proper replacement domain so we can sort this out.

Unable to Request Beta License Key “invalid domain name”

If you get an “invalid domain name” when registering for a beta license key for standalone deployment, ensure you’ve entered your domain without a protocol, e.g. company.com without http:// or https://. If a protocol is added, you’ll get the invalid domain name error.

Other reasons might be that you added a * (a “wildcard”) character to the domain, or a path such as company.com/ourapp.

License Expired (Server)

Invalid license key. Failed to activate PSPDFKit for ‘com.pspdfkit.cli’. Error: The PSPDFKit binary (CLI) is too new for your license. Your license is valid for binaries compiled until 2020-03-24. (Framework Date: 2020-04-28) Contact [email protected] with your current license details to extend your support/update period.

This error pops up when your Document Engine license has expired. Please reach out to [email protected] to renew your license.

License Expired (Web Standalone or Electron)

Error: The PSPDFKit binary (PSPDFKit for Web) is too new for your license. Your license is valid for binaries compiled until 2020-01-25. (Framework Date: 2020-02-13)”

This error is displayed if you renewed your license but didn’t log in to the PSPDFKit Portal to get the new license keys. License keys change upon renewing and need to be updated. The existing ones keep working for old versions, but once you upgrade to a newer SDK, you need the new license key.

Unknown Activation Key (Server)

[error] 2020-05-25 10:43:10.596 Activation failed: Unknown activation key. Please contact [email protected] with your activation key “”

This error means the activation key you used is invalid. Make sure you copy it correctly from the PSPDFKit Portal and that you’re not using the activation key for a deleted installation.

This error also happens if the ACTIVATION_KEY environment variable wasn’t passed to the server container correctly. Refer to our deployment guides to see how to deploy the server with major cloud infrastructure providers.

Invalid Activation Key (Server)

[error] 2020-05-14 10:10:00.1111 Activation failed: Unknown activation key. Please contact [email protected] with your activation key “fAXSOwWavLxrHZ5_SxydE3jvHv7QZh3C0E485abMDDEGKjswWuzE9gAZLCX4tvhF3oPKyiGBQsXwDta30c-WJkSknOzi4EuS4RiYlA33Z3gybqlC4dggUwrXA-SRDChuLxSvcYnCtAbVWEtbNWnQX5pOyr_9vkVRaNau2M3H_IiXJ-P5Ml9UYUNPMQggeMImrddGxksgqrFw3Rav0RCSwkNVpuRd6Yf6NgkXMRKlTG_CjGe9L9D8cunIn-bQ4u0gD-AZBJfN_MimNZplNtC0uSDMhWa9l3md47dHZ7SeWhpJcVJfZE9ujFRu81q65U3vi10qZDvvXxiwLeR1_DLEib1QeXicKClC2djDCQLyaTj5fFMyRC173AV1ZFHJ1T23NHCCsLKFZ091cMCOtrVdqMw4_EKYNSd8a84HNgj_Zx2EF5ysMyGkkJmc3KMqI_CZDOYuMUVuWcVof_qWmTL537Hn59z0d77OPwUEcPUPibvYC_WJFNa2AdlgKmSqlmgQExYzpZB9RpgKg==”

Another version of this error is a failure at startup:

+ exec /srv/pspdfkit/bin/pssync foreground
[info] 2020-12-04 14:12:51.169 Application pssync exited: exited in: PS.Application.start(:normal, [])
** (EXIT) an exception was raised:
** (MatchError) no match of right hand side value: <<203, 157, 7, 126, 59, 69, 202, 202, 152, 130, 160, 140, 173, 114, 185, 190, 190, 186, 155, 227, 248, 253, 255, 133, 19, 68, 3, 182, 173, 26, 192, 170>>
(pssync 0.1.0) lib/ps/licensing.ex:301: PS.Licensing.decrypt_license_data/1
(pssync 0.1.0) lib/ps/application.ex:400: PS.Application.resolve_license/2
(pssync 0.1.0) lib/ps/application.ex:232: PS.Application.create_default_app/0
(pssync 0.1.0) lib/ps/application.ex:103: PS.Application.start/2
(kernel 6.5.2) application_master.erl:277: :application_master.start_it_old/4 pid=<0.2080.0>
{"Kernel pid terminated",application_controller,"{application_start_failure,pssync,{bad_return,{{'Elixir.PS.Application',start,[normal,[]]},{'EXIT',{{badmatch,<<203,157,7,126,59,69,202,202,152,130,160,140,173,114,185,190,190,186,155,22
Kernel pid terminated (application_controller) ({application_start_failure,pssync,{bad_return,{{'Elixir.PS.Application',start,[normal,[]]}

This error means you’re accidentally using the license key for Standalone deployment (a string with more than 500 characters) — not the activation key (~30 characters) — to activate PSPDFKit for Web. The Server-based version requires an activation key:

  1. From the PSPDFKit Portal you’ll find a section called Server Installations.

  2. For production, you should activate a production key using the Activate… > Production dropdown option.

  3. From there, you can pass the activation key to the ACTIVATION_KEY environment variable for the server container (in docker-compose.yml or another configuration file).

Already Activated Installation (Server)

[error] 2020-05-25 10:23:18.258 A new activation key was found, but changing the license is not allowed because the currently active license is a production license and can only be activated once. The server will be started the with the already activated license.

This error message indicates that the server was started with a different production activation key before.

If you use multiple nodes, make sure to use the same activation key as you do for the first node.

If you need to change the activation key for this server installation (e.g. because you used an activation key from a different installation by mistake), you will need to reset the license information stored in the Postgres database. Please contact us via support and mention this guide article, as we’ll need to delete your installation in the PSPDFKit Portal. Then follow these steps:

  1. Stop (shut down) your server.

  2. Make a backup of the PostgreSQL database.

  3. Delete data from the license-specific apps table.

  4. Start the server with the new activation key.

Already Used Activation Key

[error] 2020-06-12 07:58:17.930 Activation failed: Installation is already activated. Please contact [email protected] with your activation key “xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”

Once an activation key is used to activate an installation, it can’t be used anymore. You’ll see this error message if you’re trying to reuse the activation key with Document Engine connecting to an empty database. This error will also show up when you drop the entire database and restart the server with the same activation key that you used before.

Invalid License Key (Server)

You might receive a cryptic error like this on startup:

11:19:41.229 [info]  Application pssync exited: exited in: PS.Application.start(:normal, [])
    ** (EXIT) an exception was raised:
        ** (MatchError) no match of right hand side value: false
            (pssync) lib/ps/application.ex:235: PS.Application.create_default_app/0
            (pssync) lib/ps/application.ex:103: PS.Application.start/2
            (kernel) application_master.erl:277: :application_master.start_it_old/4
pid=<0.44.0> module=application_controller
** (Mix) Could not start application pssync: exited in: PS.Application.start(:normal, [])
    ** (EXIT) an exception was raised:
        ** (MatchError) no match of right hand side value: false
            (pssync) lib/ps/application.ex:235: PS.Application.create_default_app/0
            (pssync) lib/ps/application.ex:103: PS.Application.start/2
            (kernel) application_master.erl:277: :application_master.start_it_old/4

If this happens, it means the value you specified for the LICENSE_KEY is invalid. Please check that you copied it exactly as it’s displayed in the PSPDFKit Portal and that it contains no leading or trailing spaces. Afterward, try running the server again.

Invalid License Key

2020-12-07 15:49:42.476 [error] Failed to decrypt license key. Please refer to https://pspdfkit.com/guides/web/troubleshooting/license-troubleshooting/#invalid-license-key

This means the LICENSE_KEY you configured for Server is invalid. Make sure you copied the correct license key from the PSPDFKit Portal.

404 When Pinging Licensing Server (Server)

You might receive an error like this on startup:

pspdfkit_1  | [error] 2020-06-25 15:02:02.661 License ping failed: {:ok, 404, [{"Date", "Thu, 25 Jun 2020 15:02:01 GMT"}, {"Content-Type", "text/html; charset=utf-8"}, {"Content-Length", "1351"}, {"Connection", "keep-alive"}, {"Vary", "Accept-Encoding"}, {"X-Request-Id", "204bafaa-cf02-45d3-ba37-5da4a5b02778"}, {"X-Runtime", "0.009876"}, {"Strict-Transport-Security", "max-age=31536000"}, {"Server", "PSPDFKit"}], "<!DOCTYPE html>\n<html>\n<head>\n  <title>The page you were looking for doesn't exist (404)</title>\n  <style>\n  body {\n    background-color: #EFEFEF;\n    color: #2E2F30;\n    text-align: center;\n    font-family: arial, sans-serif;\n  }\n\n  div.dialog {\n    width: 25em;\n    margin: 4em auto 0 auto;\n    border: 1px solid #CCC;\n    border-right-color: #999;\n    border-left-color: #999;\n    border-bottom-color: #BBB;\n    border-top: #B00100 solid 4px;\n    border-top-left-radius: 9px;\n    border-top-right-radius: 9px;\n    background-color: white;\n    padding: 7px 4em 0 4em;\n  }\n\n  h1 {\n    font-size: 100%;\n    color: #730E15;\n    line-height: 1.5em;\n  }\n\n  body > p {\n    width: 33em;\n    margin: 0 auto 1em;\n    padding: 1em 0;\n    background-color: #F7F7F7;\n    border: 1px solid #CCC;\n    border-right-color: #999;\n    border-bottom-color: #999;\n    border-bottom-left-radius: 4px;\n    border-bottom-right-radius: 4px;\n    border-top-color: #DADADA;\n    color: #666;\n    box-shadow:0 3px 8px rgba(50, 50, 50, 0.17);\n  }\n  </style>\n</head>\n\n<body>\n  <!-- This file lives in public/404.html -->\n  <div class=\"dialog\">\n    <h1>The page you were looking for doesn't exist.</h1>\n    <p>You may have mistyped the address or the page may have moved.</p>\n  </div>\n  <p>If you are the application owner check the logs for more information.</p>\n</body>\n</html>\n"} pid=<0.2359.0>
pspdfkit_1  | [warn]  2020-06-25 15:02:02.661  Error contacting licensing server. pid=<0.2359.0>
pspdfkit_1  | [info]  2020-06-25 15:02:02.665  Application pssync exited: exited in: PS.Application.start(:normal, [])

If so, there might be an issue with the currently stored license in your DB. Resetting the apps table as described below should solve this:

  1. Stop (shut down) your server.

  2. Make a backup of the PostgreSQL database.

  3. Delete data from the license-specific apps table.

  4. Start the server again.

In case this keeps happening after doing these steps, please reach out to us on support.

Delete Data from the License-Specific Apps Table

See Already Activated Installation (Server) or 404 When Pinging Licensing Server (Server) for more information.

Connect to your PostgreSQL database instance and run the SQL statement DELETE FROM apps;. This will only delete data from the license-specific apps table in the database, and it’ll leave all your document data intact.

If you’re running PostgreSQL in a container, you can find the PostgreSQL container ID via the docker ps command. Then execute the following command:

docker exec -it 78540efc1340 psql -U pspdfkit -c 'DELETE FROM apps;'

ℹ️ Note: 78540efc1340 needs to be replaced with your container ID!

Docker Delete From Apps

Adding Document Engine Firewall Rules

We don’t have a static IP that can be used in the firewall rules. Document Engine makes requests to our licensing server on start and then periodically afterward. The licensing server runs under the my.pspdfkit.com domain, and we communicate with it over HTTPS, using port 443.

Additional Help

Please look through our general Troubleshooting section for non-license-related issues (e.g. incorrect response MIME type).

Removed Trial License Requirement

We removed the requirement for a trial license key in version 2021.4.2, so you no longer need to one to try our SDK.