--- title: "Licensing Problems" description: "Resolve missing, invalid, or expired licenses and understand the Unlicensed state" source_url: https://ai-ops.com/docs/troubleshoot/licensing --- # Licensing Problems The license is the platform gate. When it is missing, invalid, or expired, licensed functionality is restricted and every device, tag, model, and binding falls back to an **Unlicensed** state. This page explains each license condition, the grace-period countdown, why entities report code `999`, and what to do when upload or activation fails. The current license state lives at **System > License**. Koios also raises a system alert (and, during a grace period, a persistent footer banner) the moment a license problem appears. --- ## License States at a Glance The **System > License** page shows a status banner reflecting the current condition: | Status | Meaning | |--------|---------| | **Active** | License is valid and licensed features are available | | **Grace Period** | License has expired, but the platform keeps running for up to 30 days | | **No License** | No license file has been uploaded — activation is required | | **Invalid** | License is expired, corrupted, or does not match the current hardware | Only the **Active** state runs the platform normally. In the other three, licensed functionality is restricted until you resolve them. --- ## No License Found If no license file has been uploaded, Koios raises the **No License Found** alert and runs in a limited state: you can log in and configure devices, tags, and models, but licensed functionality stays unavailable until a valid license is present. This is the expected state on a fresh install before activation, and after a skip during the first-login onboarding flow. **To fix it**, activate a license: 1. Go to **System > License**. 2. Follow the activation wizard (enter your license key, submit the request file to the portal, upload the returned `koios.lic`). 3. On success, the banner returns to **Active** and the platform resumes normal operation. The full walkthrough lives in [Licensing Koios](https://ai-ops.com/docs/installation/licensing.md). The **System > License** page runs the same wizard shown on first login — see [License](https://ai-ops.com/docs/system/license.md). > [!NOTE] Need a license key? > Contact your Ai-OPs representative to obtain a license key for your deployment. The key is what you paste in the first step of the activation wizard. --- ## License Invalid or Expired When a license is present but not valid, Koios raises the **License Invalid** alert (an error-severity condition) and shows the license's own error text where available. A license is invalid when it is expired past its grace period, corrupted, or bound to different hardware than the current machine. Because the Koios license is tied to the hardware it was activated on, moving the container to a new server or VM invalidates the existing license file. **To fix it:** 1. Open **System > License** and read the **License Details** card — check the **Expires** date and confirm the **Hardware ID** matches the machine Koios is running on. 2. If the license expired, obtain a renewed `koios.lic` from the portal and re-upload it. 3. If you moved Koios to different hardware, start a re-activation to generate a fresh activation request file for the current hardware, submit it to the portal, and upload the new license. > [!WARNING] Hardware-tied license > The license is bound to the hardware fingerprint it was activated on. Moving Koios to different hardware invalidates the existing license file — you must generate a new activation file and obtain a new license from the portal. See [Re-Activation](https://ai-ops.com/docs/system/license.md). --- ## Grace Period Countdown When a license expires, Koios does not stop immediately. It enters a **30-day grace period** — the platform keeps running for those 30 days so you have time to renew without an outage. During this window the license page banner shows the grace-period state, a **License Grace Period** alert appears, and a persistent footer banner with a **Renew License** link stays visible across the app. The banner counts down the days remaining and prompts you to upload a renewed license before the grace period ends. > [!WARNING] Renew before the countdown ends > When the grace period reaches zero, the license becomes **Invalid** and licensed functionality stops until you renew. Upload your renewed license before then to avoid an interruption — click **Renew License** on the footer banner, or go to **System > License**. --- ## Why Entities Show "Unlicensed" (Code 999) When there is no valid license, individual entities do not simply go idle — they report a dedicated **Unlicensed** error code, `999`. This is the per-entity signal that the platform gate, not the entity's own configuration, is the problem. The code appears identically across devices, tags, models, and bindings: | Entity | Code | Label | Meaning | |--------|------|-------|---------| | Device | `999` | Unlicensed | The device is not covered by a valid license. | | Tag | `999` | Unlicensed | The tag is not covered by a valid license. | | Model | `999` | Unlicensed | The model is not covered by a valid license. | | Binding | `999` | Unlicensed | The binding is not covered by a valid license. | While an entity is Unlicensed, it does not operate — devices stop connecting and polling, tags stop updating, models stop running inference, and bindings stop feeding their models. The exact scope of what a license covers depends on your deployment. > [!TIP] One fix clears all of them > Code `999` is never an entity-level misconfiguration. Do not troubleshoot the individual device, tag, or model — restore a valid license (activate, renew, or re-activate on the correct hardware) and every `999` clears once the platform resumes. Scan groups have no `999` code; they use a generic exception (`99`) instead, so a scan group is not the place to look for a license problem. For the master error-code lookup and how the three diagnostic fields, status, and quality legend work, see [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md). --- ## Upload or Activation Failures If activation fails at the final step (uploading `koios.lic`), work through the wizard in order — most failures come from a mismatch between the request file, the portal, and the machine: 1. **Wrong or stale request file.** The `.req` file you submit to the portal carries this machine's hardware fingerprint. If you generated it on a different machine, or re-used an old one after moving Koios, the returned license will not validate here. Generate a fresh request file from **System > License** on the machine that will run Koios. 2. **Hardware ID mismatch.** Open the **License Details** card and confirm the **Hardware ID** on the (rejected) license matches the machine. If it differs, you activated against the wrong hardware — re-activate from the current machine. 3. **Corrupted or truncated file.** Re-download `koios.lic` from the portal and upload it again without editing or renaming its contents. 4. **Expired license.** A license that is already past its date will upload but immediately report **Invalid**. Confirm the **Expires** date and request a renewed file if needed. The **License ID**, **Request ID**, and **Hardware ID** fields on the license page are copyable — copy the **Request ID** and **Hardware ID** when contacting support so they can match your activation against the portal record. See [Collecting Diagnostics for Support](https://ai-ops.com/docs/troubleshoot/collecting-diagnostics.md). > [!CAUTION] Keep your license across upgrades and restores > The license lives on its own volume and is included in backup and restore. When you back up, restore, or move a deployment, keep the license volume with the others so activation survives — otherwise the platform comes back up in the **No License Found** state. See [Backup & Restore](https://ai-ops.com/docs/system/backup.md). --- ## What's Next - [Reading Status, Quality & Errors](https://ai-ops.com/docs/troubleshoot/reading-status-and-errors.md): the shared reference for the three diagnostic fields, the status and quality legend, and the master error-code lookup (including `999`) - [License](https://ai-ops.com/docs/system/license.md): view license status and details, and run the re-activation wizard - [Licensing Koios](https://ai-ops.com/docs/installation/licensing.md): the detailed step-by-step activation walkthrough - [Backup & Restore](https://ai-ops.com/docs/system/backup.md): keep the license volume with your backups - [Collecting Diagnostics for Support](https://ai-ops.com/docs/troubleshoot/collecting-diagnostics.md): what to gather before opening a support ticket - [Troubleshooting Koios](https://ai-ops.com/docs/troubleshoot/introduction.md): the symptom router for every other class of problem