--- title: "License troubleshooting | Document Engine" canonical_url: "https://www.nutrient.io/guides/document-engine/license/troubleshooting/license-troubleshooting/" md_url: "https://www.nutrient.io/guides/document-engine/license/troubleshooting/license-troubleshooting.md" last_updated: "2026-11-09T00:00:00.000Z" description: "Learn about common license issues and solutions for Document Engine. This comprehensive guide covers common errors, activation FAQs, updates, and more." --- # 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](https://www.nutrient.io/guides/web/license/troubleshooting/license-troubleshooting.md) 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](https://www.nutrient.io/contact-sales/) if you have any questions related to your license. ## Domain registration and subdomain use See the guide on how to [configure domain and subdomain access in Document Engine](https://www.nutrient.io/guides/document-engine/license/domain-use-in-de.md) to learn how domain registration works when using Document Engine 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](https://my.nutrient.io/users/sign_in). - Offline licenses use a license key that works without connecting to the portal. As of [version 1.2.0](https://www.nutrient.io/guides/document-engine/changelog.md#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. As of Document Engine 1.16.0, Nutrient Web SDK (server-backed) activation keys and legacy server-backed/Processor license keys no longer work, including legacy offline license keys. Use a Document Engine activation key or offline license key instead. Document Engine activation keys normally start with the `3-` prefix. If an installation was previously activated with a legacy key, the stored license in the database or persistent storage can also block startup after upgrade. To fix this, clear the stored activated license, configure a valid Document Engine activation key or offline license key, and start Document Engine again. ### 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: ```yaml services: pspdfkit: image: pspdfkit/pspdfkit environment: ACTIVATION_KEY: 3-your-document-engine-activation-key ``` You can also use `LICENSE_KEY` instead of `ACTIVATION_KEY`. ### Receiving an activation key To receive a Document Engine activation key or offline license key, use the [Nutrient Portal](https://my.nutrient.io/users/sign_in) with the credentials provided by our [Sales team](https://www.nutrient.io/contact-sales/). Document Engine activation keys must start with the `3-` prefix. For client SDKs such as Web, iOS, or Android, see the guide on how to [configure domain and subdomain access in Document Engine](https://www.nutrient.io/guides/document-engine/license/domain-use-in-de.md) for how domain registration works. ### 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](https://www.nutrient.io/guides/document-engine/deployment/product-activation.md). ## 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](https://www.nutrient.io/guides/document-engine/license/updating-the-license.md) 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](https://developers.google.com/web/tools/chrome-devtools/javascript) of your web browser to view more details. If you use the Safari web browser, use the [Web Inspector](https://stackoverflow.com/questions/40234993/how-to-inspect-element-using-safari-browser) element of your web browser.![Nutrient Web SDK error dialog shown in the web browser](@/assets/guides/web/troubleshooting/web-error.png) **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 whose license doesn’t include that component. **Fix**: Set the `instant` option to `false` in the `PSPDFKit.load()` method, or contact our [Sales team](https://www.nutrient.io/contact-sales/) 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 has two possible causes. You might not have a valid, active production license that can link to your beta license. Or, your production license might be tied to 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 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 differs from the domain shown in the browser that loads the Nutrient Web SDK viewer. **Fix**: Register your production domain as the domain where the Web SDK viewer runs. Provide the [`serverUrl`](https://www.nutrient.io/api/web/PSPDFKit.Configuration.html#serverUrl) when initializing the Web SDK so it knows Document Engine isn’t running under the same domain. Domains that end with `.local` are meant for development or intranet purposes — never register them as production domains. If you’ve registered something similar as your production domain, contact our [Sales team](https://www.nutrient.io/contact-sales/) to set it up for you. If you accidentally registered a `.local` domain as a production domain, contact our [Support team](https://support.nutrient.io/hc/en-us/requests/new) and provide the replacement 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 [support](https://support.nutrient.io/hc/en-us/requests/new). **Explanation**: This error occurs when your Document Engine license has expired. **Fix**: Contact our [Sales team](https://www.nutrient.io/contact-sales/) to renew your license. For production licenses, expiration doesn’t stop Document Engine from running. Instead, it prevents upgrading to versions released after the license expiration date. However, non-production licenses (such as development or beta) will stop working once expired. We strongly recommend using production licenses in all production environments to ensure service continuity and contract compliance. ### Unknown activation key **Error message**: [error] 2020-05-25 10:43:10.596 Activation failed: Unknown activation key. Please contact support@nutrient.io with your activation key "" **Explanation**: This error occurs if the activation key you used is invalid, or if you didn’t pass `ACTIVATION_KEY` to the Document Engine container correctly. **Fix**: Make sure you copy the activation key correctly from the [Nutrient Portal](https://my.nutrient.io/users/sign_in) and that you’re not using the activation key for a deleted installation. Refer to our [deployment guides](https://www.nutrient.io/guides/document-engine/deployment/aws.md) 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 support@nutrient.io 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: ```erlang + 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**: Document Engine didn’t accept the value supplied in `ACTIVATION_KEY` or `LICENSE_KEY`. This could happen if you use a license key issued for Nutrient Web SDK instead of a Document Engine credential. It could also happen if the supplied value is invalid for another reason. **Fix**: Supply the credential issued for the Document Engine license itself, not one issued for another product. 1. Log in to the [Nutrient Portal](https://my.nutrient.io/users/sign_in) 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. Document Engine activation keys start with the `3-` prefix. 3. Pass the value in the `ACTIVATION_KEY` environment variable for the Document Engine container, located in `docker-compose.yml` or another configuration file. Both variable names accept either credential type. For an offline license, the credential is a license key rather than a short activation key. Refer to [product activation](https://www.nutrient.io/guides/document-engine/deployment/product-activation.md) for both license types. ### Invalid license key **Error message**: 2020-12-07 15:49:42.476 [error] Failed to decrypt license key. Please refer to https://www.nutrient.io/guides/document-engine/troubleshooting/license/license-troubleshooting/#invalid-license-key You can also encounter a startup error as follows: ```erlang 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](https://my.nutrient.io/users/sign_in) 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"}], "\n\n\n The page you were looking for doesn't exist (404)\n \n\n\n\n \n
\n

The page you were looking for doesn't exist.

\n

You may have mistyped the address or the page may have moved.

\n
\n

If you are the application owner check the logs for more information.

\n\n\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](#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](https://support.nutrient.io/hc/en-us/requests/new). ## Delete data from the license-specific apps table See [404 when pinging the Nutrient Portal](#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: ```sh docker exec -it 78540efc1340 psql -U pspdfkit -c 'DELETE FROM apps;' ``` In the command above, replace **`78540efc1340`** with your container ID.![Docker Delete From Apps](@/assets/guides/web/troubleshooting/web-docker-delete-from-apps.png) ## Adding Document Engine firewall rules Document Engine makes requests to the [Nutrient Portal](https://my.nutrient.io/users/sign_in) on start and then periodically (every two hours) afterward. The [Nutrient Portal](https://my.nutrient.io/users/sign_in) runs under the `my.nutrient.io` domain, and we communicate with it over HTTPS, using port `443`. We recommend allowing `my.nutrient.io` by hostname in your firewall rules. If your firewall requires a static IP address, contact our [Support team](https://support.nutrient.io/hc/en-us/requests/new) for advice. ## Additional help For more information, refer to our general [troubleshooting](https://www.nutrient.io/guides/document-engine/troubleshoot.md) guide to find tips and tricks on a wide range of topics related to Document Engine.