License Troubleshooting

PSPDFKit for Web is a commercial SDK and requires a license to work. We issue one license per explicit domain. Contact sales@pspdfkit.com 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.

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 science.weylandcorp.com and access a PDF via science.weylandcorp.com/yutani/overview. This is correct, since the domain and subdomain match. The path — yutani/overview — is not relevant for licensing.

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 are developing via bg386-dev.weylandcorp.com. The production license will not work on the development domain, as the domain does not match.
Fix: Register an additional developer license via our Customer 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 PSPDFKit Server 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 PSPDFKit Server 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 Customer 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:

Copy
1
2
3
4
5
6
// 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 our Customer Portal with the credentials you received from our sales team.

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.

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:

1
2
3
4
5
services:
  pspdfkit:
    image: pspdfkit/pspdfkit
    environment:
      ACTIVATION_KEY: obiWMzt3XouUsAiwyWGSrC7RMdSv5hME

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

The activation key is stored in the connected PostgreSQL database. If you accidentally purge the database, you need to contact sales@pspdfkit.com 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 Customer Portal again.

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

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 feature that is not included in your license.

Set the instant option to false in PSPDFKit.load() or add the Instant feature 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 sales@pspdfkit.com with your requirements for a new license

If you see this message, the domain you registered in the Customer Portal does not 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 usage through the Customer Portal:

  1. Log in to the Customer 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 will 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 PSPDFKit Server: PSPDFKit Server 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 sales@pspdfkit.com with your current license details to extend your support/update period.

This error pops up when your PSPDFKit Server license has expired. Please reach out to sales@pspdfkit.com 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 did not log in to our Customer 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 support@pspdfkit.com with your activation key “

This error means the activation key you used is invalid. Make sure you copy it correctly from the Customer 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 support@pspdfkit.com with your activation key “fAXSOwWavLxrHZ5_SxydE3jvHv7QZh3C0E485abMDDEGKjswWuzE9gAZLCX4tvhF3oPKyiGBQsXwDta30c-WJkSknOzi4EuS4RiYlA33Z3gybqlC4dggUwrXA-SRDChuLxSvcYnCtAbVWEtbNWnQX5pOyr_9vkVRaNau2M3H_IiXJ-P5Ml9UYUNPMQggeMImrddGxksgqrFw3Rav0RCSwkNVpuRd6Yf6NgkXMRKlTG_CjGe9L9D8cunIn-bQ4u0gD-AZBJfN_MimNZplNtC0uSDMhWa9l3md47dHZ7SeWhpJcVJfZE9ujFRu81q65U3vi10qZDvvXxiwLeR1_DLEib1QeXicKClC2djDCQLyaTj5fFMyRC173AV1ZFHJ1T23NHCCsLKFZ091cMCOtrVdqMw4_EKYNSd8a84HNgj_Zx2EF5ysMyGkkJmc3KMqI_CZDOYuMUVuWcVof_qWmTL537Hn59z0d77OPwUEcPUPibvYC_WJFNa2AdlgKmSqlmgQExYzpZB9RpgKg==”

This error means you’re accidentally using the license key — not the activation key — to activate PSPDFKit for Web. The server-based version requires an activation key:

  1. From the Customer 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 will need to delete your installation in the Customer Portal. Then follow these steps:

  1. Stop (shut down) your server.
  2. Make a backup of the PostgreSQL database.
  3. 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 will leave all your document data intact.
  4. Start the server with the new activation key.

If you are evaluating, open the Example Projects guide, where you should see a yellow box with an activation key and a future expiration date. Update your environment configuration and set ACTIVATION_KEY to the new trial key shown in the step above. Empty PostgreSQL or perform the above steps to apply the new key.

Already Used Activation Key

[error] 2020-06-12 07:58:17.930 Activation failed: Installation is already activated. Please contact support@pspdfkit.com 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 PSPDFKit Server 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:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
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 Customer Portal and that it contains no leading or trailing spaces. Afterward, try running the server again.

404 When Pinging Licensing Server (Server)

You might receive an error like this on startup:

Copy
1
2
3
4
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. 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 will leave all your document data intact.
  4. Start the server again.

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

Additional Help

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