License troubleshooting for Document Engine

This guide covers common license issues and their solutions for Document Engine. To learn about common license issues and their solutions for Nutrient Web SDK, refer to our license troubleshooting for Nutrient Web SDK guide.

Document Engine is a commercial product and requires a license to work. We provide one activation key for one production installation, and one development activation key for all development installations. Contact our Sales team if you have any questions related to your license.

Domain registration and subdomain use

Refer to the guide on how to configure domain and subdomain access in Document Engine to learn how domain registration works with Document Engine when using it with Nutrient SDKs.

License types

Document Engine supports two license types: online and offline.

• Online licenses use an activation key to register the license with the Nutrient Portal.

• Offline licenses use a license key that works without connecting to the portal.

As of version 1.2.0, Document Engine supports both license types using either the ACTIVATION_KEY or LICENSE_KEY environment variable. You can use either variable name to provide your license credentials, regardless of the license type.

Adding a license in Docker Compose

To set up a license in a Docker Compose deployment, add the key to your docker-compose.yml file as follows:

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

You can also use LICENSE_KEY instead of ACTIVATION_KEY.

Receiving an activation key

To receive an activation key, configure your domain for the client SDK licenses — for example, Web, iOS, or Android — and link those to your Document Engine license. This can be done through the Nutrient Portal using the credentials provided by our Sales team. Refer to the guide on how to configure domain and subdomain access in Document Engine to learn how domain registration works with Document Engine when using it with Nutrient SDKs.

Reactivating licenses

You can activate or reactivate your Document Engine installation at any time by providing a new activation or license key. If you move your deployment or need to reset the installation, update the environment variable with your new key and restart the service.

To learn more, refer to our step-by-step guide for product activation.

Handling license updates

If you extend your license or add new features to it, there’s no need to replace the activation key. Instead, follow the steps in the updating the activated license guide.

Error and warning messages

This section covers the most common errors and warning messages that may occur, what they mean, and how to fix them.

Missing feature

If an error message as shown below appears on your screen, open the JavaScript Console of your web browser to view more details. If you use Safari web browser, use the Web Inspector element of your web browser.

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

Explanation: This error occurs because you’re trying to connect the Nutrient Web SDK JavaScript library to a server with a component that isn’t included in your license.

Fix: Set the instant option to false in the PSPDFKit.load() method , or contact our Sales team to add the Instant component to your license.

Unable to request beta license key

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

Explanation: This error occurs because you don’t have a valid, active production license that can be linked to your beta license or your production license might be registered with a different domain name than the one you’re trying to use for beta.

Fix: Before requesting a license key for beta testing/development purposes, you must first request a production ID (license) with a matching domain name. Afterward, you can to proceed to request a beta license.

Mismatched domain when using Web SDK with Document Engine

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

Explanation: This error occurs because the domain registered in your license is different than the domain visible in the web browser displaying the page that loads the Nutrient Web SDK viewer.

Fix: Register your production domain as the domain where the Web SDK viewer is used and provide the serverUrl when initializing the Web SDK to inform it that Document Engine isn’t running under the same domain.

License expired

Error message: Invalid license key. Failed to activate Nutrient for ‘com.pspdfkit.cli’. Error: Nutrient Licensing Issue: Your license is too old for Nutrient Core Daemon 1.0. Please visit our customer portal at https://my.nutrient.io/ to download your new license key. If you’re not able to proceed, contact us at https://www.nutrient.io/support/request/.

Explanation: This error occurs when your Document Engine license has expired.

Fix: Contact our Sales team to renew your license.

Unknown activation key

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

Explanation: This error occurs if the activation key you used is invalid or if the ACTIVATION_KEY environment variable wasn’t passed to Document Engine container correctly.

Fix: Make sure you copy the activation key correctly from the Nutrient Portal and that you’re not using the activation key for a deleted installation. Refer to our deployment guides to see how to deploy Document Engine with major cloud infrastructure providers.

Invalid activation key

Error message: [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,[]]}

Explanation: This error occurs if you’re accidentally using the license key for Nutrient Web SDK alone (a string with more than 500 characters) and not the activation key (~30 characters) to activate Nutrient Web SDK with Document Engine.

Fix: Follow the steps below to activate your Nutrient Web SDK with Document Engine license:

1. Log in to the Nutrient Portal and navigate to the Licenses section to select your Document Engine license.

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

3. Pass the activation key to the ACTIVATION_KEY environment variable for the Document Engine container, located in docker-compose.yml or another configuration file.

Invalid license key

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

You can also encounter a startup error as follows:

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

Explanation: This error occurs because the value you specified for the LICENSE_KEY is invalid.

Fix: Check that you copied the license key exactly as it’s displayed in the Nutrient Portal and that it contains no leading or trailing spaces. Afterward, try running Document Engine again.

404 when pinging the Nutrient Portal

Error message: You can encounter a startup error as follows:

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, [])

Explanation: This error occurs because of an issue with the currently stored license in your database.

Fix: Reset the apps table as described below:

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.

If the error keeps occurring after performing the steps above, contact our Support team.

Delete data from the license-specific apps table

See 404 when pinging the Nutrient Portal for more information.

Connect to your PostgreSQL database instance and run the SQL statement: DELETE FROM apps;. The SQL statement only deletes data from the license-specific apps table in the database, leaving all your document data intact.

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

docker exec -it 78540efc1340 psql -U pspdfkit -c '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 the Nutrient Portal on start and then periodically (every two hours) afterward. The Nutrient Portal runs under the my.nutrient.io domain, and we communicate with it over HTTPS, using port 443.

Additional help

For more information, refer to our general troubleshooting guide to find tips and tricks on a wide range of topics related to Document Engine.