--- title: "License troubleshooting | Nutrient Web SDK" canonical_url: "https://www.nutrient.io/guides/web/troubleshooting/license-troubleshooting/" md_url: "https://www.nutrient.io/guides/web/troubleshooting/license-troubleshooting.md" last_updated: "2026-05-14T16:53:43.944Z" description: "Learn about common license issues and solutions for Nutrient Web SDK. This comprehensive guide covers common errors, activation FAQs, updates, and more." --- # License troubleshooting for Nutrient Web SDK This guide covers common license issues and their solutions for Nutrient Web SDK. To learn about common license issues and their solutions for Document Engine, refer to the [license troubleshooting for Document Engine](https://www.nutrient.io/guides/document-engine/troubleshooting/license/license-troubleshooting.md) guide. Nutrient Web SDK is a commercial SDK and requires a license to work. We issue one license per explicit domain. Contact our [Sales team](https://www.nutrient.io/contact-sales) if you have any questions related to your license. ## Domain registration and subdomain use The domain you register must match the domain where the SDK is used exactly, **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 when your application is loaded exactly. ### Example scenarios The following example scenarios illustrate how to correctly register your domain. - **Scenario**: You register a domain named `weylandcorp.com` on the [Nutrient Portal](https://my.nutrient.io/users/sign_in) but use `www.weylandcorp.com` when your application is loaded. In such a case, your license won’t work. **Fix**: Redirect `www.weylandcorp.com` to `weylandcorp.com`. - **Scenario**: You register a domain named `www.weylandcorp.com` but use `spaceship.weylandcorp.com` when your application is loaded. In such a case, your license won’t work. **Fix**: Register the domain `spaceship.weylandcorp.com` on the [Nutrient Portal](https://my.nutrient.io/users/sign_in). - **Scenario**: You register a domain named `pdf.yutanicorp.com` and display documents using the domain `viewer.yutanicorp.com/pdf/eca`. As the subdomains don’t match (`pdf` vs `viewer`), your license won’t work. **Fix**: Register the domain `viewer.yutanicorp.com` on the [Nutrient Portal](https://my.nutrient.io/users/sign_in). - **Scenario**: Your production domain is `science.weylandcorp.com` but you’re developing using a domain named `bg386-dev.weylandcorp.com`. The production license won’t work on the development domain, as the domains don’t match. **Fix** Register your developer domain (`bg386-dev.weylandcorp.com`) on the [Nutrient Portal](https://my.nutrient.io/users/sign_in) to run the developer instance. - **Scenario**: Your production domain is `science.weylandcorp.com` and you’re hosting Document Engine at `pspdfkit.weylandcorp.com`. In such a case, your license won’t work. **Fix**: Register `science.weylandcorp.com` as the domain where the Web SDK is used and provide the [`serverUrl`](https://www.nutrient.io/api/web/interfaces/Configuration.html#serverurl) when initializing the Web SDK to inform it that Document Engine isn’t running under the same domain. - **Scenario**: You registered your production domain but face issues with your local development domain. **Fix**: Log in to the [Nutrient Portal](https://my.nutrient.io/users/sign_in) and request a license for `localhost` using the **Request License Key for Web Beta Usage** button. ## License types Nutrient Web SDK can run locally in the browser or work together with Document Engine. Licensing is different depending on this choice, as explained below. ### Nutrient Web SDK in the browser In this case, the Web SDK uses a license key, which is passed as part of the `NutrientViewer.load()` method: ```javascript // Activate Nutrient Web SDK for `yourdomain.com`. NutrientViewer.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 receive a domain license key, register your domain in the [Nutrient Portal](https://my.nutrient.io/users/sign_in) using the credentials provided by our Sales team.![Web License Key](@/assets/guides/web/troubleshooting/web-license-key.png) If an error occurs, check the [JavaScript Console](https://developers.google.com/web/tools/chrome-devtools/javascript) of your web browser for more details. If you use Safari web browser, use the [Web Inspector](https://stackoverflow.com/questions/40234993/how-to-inspect-element-using-safari-browser) element of your web browser. The most common issues are copy/paste issues where a few characters are missing, or use of a key that doesn’t match your domain. If you’ve renewed your license recently, make sure to use the updated license key. 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. To learn more about Nutrient Web SDK licensing, refer to our detailed [licensing](https://www.nutrient.io/guides/web/pspdfkit-for-web/licensing.md#setting-up-a-domain-in-our-customer-portal) guide. ### Nutrient Web SDK with Document Engine When using Web SDK with Document Engine, refer to the [license troubleshooting for Document Engine](https://www.nutrient.io/guides/document-engine/troubleshooting/license/license-troubleshooting.md) guide for details on license types. ## API key vs license key Nutrient offers two distinct authentication methods depending on the product: | | License Key (Web SDK) | API Key (Document Web Services) | | ------------- | ------------------------------------------ | ------------------------------------------ | | **Used with** | Nutrient Web SDK (standalone) | Document Web Services (DWS) Viewer | | **Format** | Long encoded string (~500+ characters) | Short alphanumeric string (~40 characters) | | **Passed to** | `NutrientViewer.load({ licenseKey:... })` | Backend authentication for DWS API | | **Found in** | [Nutrient Portal](https://my.nutrient.io/users/sign_in) → Manage Licenses | [Nutrient Portal](https://my.nutrient.io/users/sign_in) → DWS → API Keys | ### Common mistake: Using a DWS API key in the Web SDK If you subscribe to Document Web Services (DWS) and attempt to use your DWS API key in the Web SDK `licenseKey` field, the SDK returns a "Could not decode license key" error: ``` PSPDFKitError: Could not decode license key ``` **This happens because:** - The DWS API key authenticates your backend server with the DWS API - The Web SDK license key activates the SDK in the browser for your domain - These are different products with different authentication mechanisms ### How to identify which key you have **DWS API key** — Short, looks like: `dws_live_abc123xyz456...` **Web SDK license key** — Long encoded string, looks like: `nX5NbnzGFzYhuWTje1LqC8hWYX...` (500+ characters) ### Which product do I have? If you’re unsure which Nutrient product you purchased: 1. Log in to the [Nutrient Portal](https://my.nutrient.io/users/sign_in) 2. Check your dashboard: - **Web SDK** appears under **Manage Licenses** with domain registrations - **DWS** appears under **Document Web Services** with API key management 3. Review your purchase confirmation or contact our [Sales team](https://www.nutrient.io/contact-sales) for clarification For a detailed comparison of Web SDK vs. DWS capabilities, refer to the [product comparison](https://www.nutrient.io/sdk) page. ## Handling license updates For Web SDK deployments with Document Engine, refer to the [license troubleshooting for Document Engine](https://www.nutrient.io/guides/document-engine/troubleshooting/license/license-troubleshooting.md) guide for details. For only Web SDK deployments, you require a new license key from the [Nutrient Portal](https://my.nutrient.io/users/sign_in). ## 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 Safari web browser, use the [Web Inspector](https://stackoverflow.com/questions/40234993/how-to-inspect-element-using-safari-browser) element of your 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 with a component that isn’t included in your license. **Fix**: Set the `instant` option to `false` in the `NutrientViewer.load()` method , or contact our [Sales team](https://www.nutrient.io/contact-sales) to add the **Instant** component to your license. ### Mismatched domain in Web SDK **Error message**: Nutrient licensing issue: Your license has been registered for a different bundle identifier: "some-domain.com" - not "actual-company-domain.com". Each Nutrient license is only valid for one explicit bundle ID and one distribution method (Enterprise or public App Store). Please contact us at https://support.nutrient.io/hc/en-us/requests/new with your requirements for a new license. **Explanation**: This error occurs because the domain you registered in the [Nutrient Portal](https://my.nutrient.io/users/sign_in) doesn’t match the domain where Nutrient Web SDK is used. We use the origin domain to check and verify. This is the domain your website is served from — the domain you see in the browser. **Fix**: To use your license with a domain such as `localhost` or `127.0.0.1` for development or demo purposes, request a license key for beta use through the [Nutrient Portal](https://my.nutrient.io/users/sign_in) by following the steps below. 1. Log in to the [Nutrient Portal](https://my.nutrient.io/users/sign_in) using your credentials. 2. In your Web SDK license row, click **Request Beta Web Domain**. 3. In the **Request Development License Key (Beta Identifier)** dialog: - Verify the prefilled **License** and **Identifier** values. - Enter your **Beta Identifier** (for example, `localhost`, `staging.website.com`, or `www.dev.website.com`). - Enter a short **Request Reason** (for example, testing, CI, QA, or local development). - Click **Continue**. 4. In the confirmation step: - Review all values (**License**, **Identifier**, **Beta Identifier**, and **Request Reason**). - Check **I have read and understood the above information**. - Click **Send Request**. 5. After submission, a confirmation banner will appear indicating the beta usage license key request was received for your beta ID. After review (typically within 1–2 business days), you’ll receive an email with the status update. ### 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 register a production ID (license) with a matching domain name. Once registered, you can proceed to request a beta license. ### Invalid domain name when requesting beta license key **Error message**: Invalid domain name **Explanation**: This error occurs if you enter a protocol in your domain when requesting a beta license key. Other reasons may include addition of a `*` (a “wildcard”) character to the domain, or a path such as company.com/ourapp. **Fix**: When registering for a beta license key for the Web SDK deployment, ensure you’ve entered your domain without a protocol, for example, company.com without http:// or https://. ### 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`](https://www.nutrient.io/api/web/interfaces/Configuration.html#serverurl) when initializing the Web SDK to inform it that Document Engine isn’t running under the same domain. Domains that end with `.local` are meant for development or intranet purposes and should never be registered 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 (Web SDK or Electron) **Error message**: Your license is too old for Nutrient for Web (Standalone) 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 if you renewed your license but didn’t log in to the [Nutrient Portal](https://my.nutrient.io/users/sign_in) to get the new license key. **Fix**: License key change upon renewing, hence you must update it. The existing one keeps working for old versions, but once you upgrade to a newer SDK, you require the new license key. ## Additional help For more information, refer to our general [troubleshooting](https://www.nutrient.io/guides/web/troubleshooting/common-issues.md) section for non-license-related issues (for example, incorrect response MIME type). ## Removed trial license requirement We removed the requirement for a trial license key in version 2021.4.2. It means you no longer need a license to try our SDK. --- ## Related pages - [How to add your license key for Nutrient Web SDK](/guides/web/troubleshooting/license/add-license-key.md) - [❌ INCORRECT: Missing `NEXT_PUBLIC_` prefix.](/guides/web/troubleshooting/license/watermark-still-appearing.md)