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:

Go to System > License.
Follow the activation wizard (enter your license key, submit the request file to the portal, upload the returned koios.lic).
On success, the banner returns to Active and the platform resumes normal operation.

The full walkthrough lives in Licensing Koios. The System > License page runs the same wizard shown on first login — see License.

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:

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.
If the license expired, obtain a renewed koios.lic from the portal and re-upload it.
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.

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.

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.

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.

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.

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:

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.
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.
Corrupted or truncated file. Re-download koios.lic from the portal and upload it again without editing or renaming its contents.
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.

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.

What's Next

Reading Status, Quality & Errors: the shared reference for the three diagnostic fields, the status and quality legend, and the master error-code lookup (including 999)
License: view license status and details, and run the re-activation wizard
Licensing Koios: the detailed step-by-step activation walkthrough
Backup & Restore: keep the license volume with your backups
Collecting Diagnostics for Support: what to gather before opening a support ticket
Troubleshooting Koios: the symptom router for every other class of problem

Service Health & Resource Alarms Server Won't Start